Skip to content
Velloreth
Developer Tools 6 min read

How to Write Good Git Commit Messages

A commit message is documentation for the future. Learn the conventions, the structure, and the habits that make history useful.

By

Why commit messages matter

A commit message is documentation written for someone who will read it months later, possibly you. The diff shows what changed; the message explains why.

The test: if you had to revert this change in six months, would the message tell you whether it is safe? A message like “fix bug” does not. A message like “Fix race condition in token refresh that logged users out” does.

The subject line

Imperative mood. Write it as a command.

Add retry logic to the payment client

Not:

Added retry logic
Adds retry logic
Adding retry logic

The imperative reads naturally when you complete the sentence “This commit will…”. It is also what Git itself uses for generated messages like “Merge branch ‘main’”.

Under 50 characters. The subject appears in git log --oneline, in GitHub’s commit list, and in many tools. Long subjects get truncated.

No trailing period. It is a title, not a sentence.

Capitalize consistently. Either always capitalize or never; the consistency matters more than the choice.

Complete the thought. “Fix bug” is not a subject. “Fix null pointer when the user has no address” is.

The body

Separate the body from the subject with a blank line.

Add retry logic to the payment client

The payment provider occasionally returns a 503 during
deployments. Previously this surfaced as a failed checkout,
which lost the sale.

Retry three times with exponential backoff, and only for
idempotent requests. Non-idempotent requests still fail fast,
because retrying them could double-charge.

Refs: #4821

Explain why. The diff shows the retry loop. The message explains that the provider returns 503 during deployments, and that only idempotent requests are retried.

Note the alternatives. If you considered a different approach and rejected it, say so. This prevents someone from “fixing” it back.

Note the consequences. A change that affects behaviour elsewhere should say so.

Wrap at 72 characters. Git does not wrap for you, and a long line is hard to read in a terminal.

Conventional Commits

A convention that adds a type prefix.

<type>[optional scope]: <description>

[optional body]

[optional footer]

The types:

  • feat — a new feature.
  • fix — a bug fix.
  • docs — documentation only.
  • style — formatting, no code change.
  • refactor — a change that neither fixes a bug nor adds a feature.
  • perf — a performance improvement.
  • test — adding or fixing tests.
  • build — build system or dependencies.
  • ci — CI configuration.
  • chore — other changes.

Examples:

feat(auth): add password reset flow
fix(api): handle empty response body
docs(readme): document the environment variables
refactor(cart): extract pricing into a module

Breaking changes are marked with ! or a footer.

feat(api)!: remove the v1 endpoints

BREAKING CHANGE: the v1 endpoints are removed. Clients must
migrate to v2.

Why it is useful. The type prefix enables automated tooling. A changelog generator can group commits by type. A release tool can determine the version bump: fix is a patch, feat is a minor, and a breaking change is a major. This is how semantic-release and similar tools work.

What not to write

“fix bug” — which bug? The message should be findable by searching for the symptom.

“WIP” — a work-in-progress commit should be squashed before merging. If it must be pushed, say what is incomplete.

“update code” — meaningless.

“asdf” — the diff is the only record of intent.

A restatement of the diff — “change the variable name from x to y” adds nothing the diff does not show. Explain why the name changed.

Committing often

Small, focused commits are easier to review, revert, and bisect.

One logical change per commit. A commit that fixes a bug and reformats a file is two commits. If the bug fix needs reverting, the reformat goes with it.

Commit when the change is complete. A commit should leave the code in a working state, so that any commit can be checked out and built.

Use git add -p to stage parts of a file, which lets you split a mixed change into focused commits.

git add -p

This walks through each hunk and asks whether to stage it.

Amending and fixing

Amend the last commit’s message:

git commit --amend

Amend the last commit’s content:

git add forgotten-file.js
git commit --amend --no-edit

Fix an older message with interactive rebase:

git rebase -i HEAD~3
# change 'pick' to 'reword' for the commit to fix

Amending rewrites history, so only do it on a branch nobody else has.

Commit messages and code review

A good commit message makes review easier, because the reviewer can read the intent before the diff. A pull request with a clear description and a sequence of well-described commits is far easier to review than one with a single “changes” commit.

The practical benefit shows up in three places. Review: the reviewer understands the goal and can judge whether the code achieves it. Debugging: a future reader can find the commit that introduced a behaviour by searching the messages. Reverting: a revert is safe when the message explains what the change does and why.

The habit worth building: write the message as if the reader has the diff in front of them and needs to know why. That reader is usually you, six months later, with no memory of the context.

Practical guidance

  • Write the subject in the imperative mood, under 50 characters.
  • Explain why in the body, not what.
  • Wrap the body at 72 characters.
  • Use Conventional Commits if you want automated changelogs.
  • One logical change per commit.
  • Use git add -p to split mixed changes.
  • Reference the issue in the footer.
  • Amend only unpushed commits.

For the related guides, see git-merge-vs-rebase and git-branching-strategies. For the broader context, semantic-versioning-explained and code-review-checklist.

Quotable summary

A commit message explains why a change was made, not what the diff already shows, because the diff is the record of what changed and the message is the record of intent. The subject line should be imperative, under 50 characters, and complete the sentence “This commit will…”, while the body explains the reasoning, the alternatives considered, and any consequences. Conventional Commits adds a type prefix such as feat, fix, or docs, which enables automated changelog generation and semantic version bumps from the history. A good message saves the next person from reading the diff to understand the intent, and the test is whether the message would tell you if the change is safe to revert in six months.

Frequently asked questions

What should a commit message contain?
A short imperative subject line describing the change, and a body explaining why the change was made, what alternatives were considered, and any consequences. The diff shows what changed; the message explains why.
What is Conventional Commits?
A convention that prefixes the subject with a type, such as feat, fix, docs, or chore, optionally with a scope. It enables automated changelog generation and semantic version bumps from the commit history.
Should the subject line be capitalized?
Either is fine as long as the project is consistent. The more important rules are the imperative mood and the length limit. Many projects use lowercase after the type prefix.
How long should a commit message be?
The subject should be under 50 characters, and the body wrapped at 72. The subject is what appears in git log --oneline and in GitHub's commit list, so it must be readable at a glance.
What is the imperative mood?
It is the form used for commands: 'Add validation', not 'Added validation' or 'Adds validation'. Git's own generated messages use it, and it reads naturally when completing 'This commit will...'.
How do I amend a commit message?
Use git commit --amend to edit the most recent commit's message. If the commit has been pushed, amending rewrites history, so only do it on a branch nobody else has.