How to Write Good Commit Messages (With Examples)

“Fixed stuff.” “WIP.” “asdf.” Scroll through almost any Git history and you will find messages that made sense for ten seconds. Months later, when you are hunting down the change that broke checkout, they tell you nothing. A good commit message takes thirty seconds to write and saves hours of archaeology. This guide covers the conventions experienced teams follow, with examples you can copy into your own workflow.

The shape of a great message

A commit message has a subject line, a blank line and an optional body. The widely used “50/72” guideline says:

• Keep the subject to about 50 characters so it fits in one-line logs and tool interfaces.
• Leave the second line blank; many tools rely on it to separate subject from body.
• Wrap the body at about 72 characters so it reads well in a terminal.

The body is where you explain why the change was needed and what alternatives you rejected. The diff already shows what changed.

Write the subject in the imperative

Git itself writes messages like “Merge branch …” and “Revert …”, so the convention is to phrase subjects as commands: “Add search filters”, not “Added search filters” or “Adds search filters”. A handy test: the subject should complete the sentence “If applied, this commit will …”.

Some before-and-after examples:

• “fixed bug” → “Fix crash when cart is empty”
• “changes” → “Rename user service to account service”
• “update” → “Bump image library to patch memory leak”

Conventional Commits in a nutshell

Conventional Commits adds a small, machine-readable structure: type(scope): description. For example, fix(auth): handle expired refresh tokens. Common types include:

• feat — a new feature (maps to a minor version bump)
• fix — a bug fix (maps to a patch bump)
• docs, style, refactor, perf, test, build, ci and chore — everything else

A breaking change is marked with an exclamation mark, as in feat(api)!: remove v1 endpoints, or a BREAKING CHANGE: footer, and triggers a major bump. Release tools can then generate changelogs and version numbers straight from the history.

How to use the generator for demos and tooling

When you build a demo repository, test a commit-lint rule or record a tutorial, you need plausible history fast. The generator above helps:

1. Leave Include scope on for messages like feat(cli): add search filters, or switch it off for the shorter type: description form.
2. Generate up to 50 messages per batch, mixing types such as feat, test, refactor, style and perf with scopes like ui, auth, docs and deps.
3. Feed them into a script that creates empty commits, or paste them into your changelog generator’s test fixtures.
4. Use the batch to check that your lint rules accept valid messages and your changelog groups them correctly.

For real work, always describe what actually changed — generic messages belong in sample data only.

Small habits that keep history clean

• One logical change per commit. If the subject needs the word “and”, consider splitting it.
• Reference the issue in the body or footer so readers can find the discussion.
• Tidy up before you share. Squash “fix typo” commits into the change they belong to before opening a pull request.
• Read your log. Run git log --oneline now and then; if it does not tell a story, adjust your habits.

A full example with body

Here is what a complete message can look like:

fix(checkout): prevent double charge on slow networks

After a blank line, the body might say: “The pay button stayed active while the request was pending, so impatient users could submit twice. Disable the button until the response arrives and make the server reject duplicate order tokens.” A footer can then list the related issue number.

In five lines, a future reader learns the symptom, the cause and both parts of the fix — without opening the diff.

Pro tips

• Write the message before you commit by asking “why would a teammate need this change?”.
• Avoid ending the subject line with a period.
• Use the body to record decisions that are not obvious from the code.
• Add a commit-msg hook or lint step so the convention is checked automatically.

Frequently asked questions