How to Write Good Git Commit Messages

Code tells you what the program does. Commit messages tell you why it changed. Six months from now, the message may be the only record of why a line exists.

Bad and good messages#

One change per commit#

An atomic commit does one logical thing. Fixing a bug, renaming a function and updating a dependency are three commits, not one. Then each can be reviewed, reverted or cherry-picked on its own.

If you have mixed several changes, use the staging area to separate them, with git add <file> or git add -p.

The subject line#

• Start with a verb in the imperative, as if giving a command: "Add", "Fix", "Remove", not "Added" or "Fixes".
• Keep it to about 50 characters. GitHub cuts off long subjects.
• Start with a capital letter, and do not end with a full stop.

A useful test is that the subject should complete this sentence: "If applied, this commit will... add rate limit to the login endpoint".

The body#

For anything that is not obvious, add a body after a blank line. Explain why the change was needed, not how the code works: the diff already shows that.

With -m used twice, the second becomes the body:

git commit -q -m "Add rate limit to the login endpoint" -m "Bots were trying thousands of passwords per minute. Allow 5 attempts per minute for each IP address."
git log -n 1

commit 41f216dad7ec0e158036d391e0c7e04bff364dde
Author: Asha Rao <[email protected]>
Date:   Thu Nov 5 09:05:00 2026 +0530

    Add rate limit to the login endpoint
    
    Bots were trying thousands of passwords per minute. Allow 5 attempts per minute for each IP address.

For longer messages, run git commit without -m, and write the message in your editor.

Conventional Commits#

Many teams use a fixed prefix, a style called Conventional Commits. Tools can then produce changelogs and version numbers automatically.

feat: add wishlist to the product page
fix: stop cart total going negative
docs: explain how to run the tests
refactor: move price logic into a helper
test: cover empty cart checkout
chore: update dependencies
feat(auth)!: require two-factor login

The word in brackets is an optional scope, and ! marks a breaking change. Use whatever style your team uses. Being consistent matters more than which style you pick.

Link to issues#

On GitHub, #12 in a commit message links to issue 12, and words such as Fixes #12 close the issue when the commit reaches the default branch.

How often should you commit?#

Often. Commit each time you reach a small working step, usually several times an hour. Small commits are easy to undo and describe. If your message needs the word "and", the commit may be too big.

Messy work-in-progress commits on your own branch are fine. You can tidy them before opening a pull request with interactive rebase, or use Squash and merge.

Common mistakes#

Practice#

Fix crash when the search box is empty
Add CSV export to the orders page
Add install steps to the README

Key takeaway#

Next: Branching Workflows.