Commit messages: how to write them

A commit message tells whoever opens the history six months later why the change was made. Most of the time that is you.

fix, updates, asdf, final2 tell your colleague nothing, and they tell you nothing either. Those lines are exactly what you search the history by, so the thirty seconds spent on a message pay off.

The shape is simple. The first line is short, roughly up to 50 characters, in the imperative and with no period at the end: what the commit does to the project. Then a blank line. Then the body, where the point is why the change was made. How it was made is visible in the diff.

$ git commit -m "Fix crash when the login form is submitted empty" -m "The handler read user.email without checking that user exists.
An empty submit produced a null user, so the page 500'd."

$ git log -1
commit c6cebf9577b5cb2bac9c2493594f89e358a40eaf
Author: Anna Petrova <anna@example.com>
Date:   Tue Jul 21 21:26:37 2026 -0400

    Fix crash when the login form is submitted empty

    The handler read user.email without checking that user exists.
    An empty submit produced a null user, so the page 500'd.

Two -m flags in a row give you a subject paragraph and a body paragraph. Run git commit with no -m and git opens an editor, which is a nicer place to write a multi-line message.

On the left is what not to write, on the right the same thing written for a human:

fix          ->  Fix crash when the login form is submitted empty
updates      ->  Add search to the sidebar
asdf         ->  Remove the unused image loader
wip2         ->  Update the Postgres driver to 3.2

Conventional commits

In many projects the first line starts with the type of the change: feat:, fix:, docs:, refactor:, test:, chore:. That gives you fix: crash on empty login form. It is an agreement, not a git rule: the types drive changelog generation and version numbers. It becomes mandatory where someone has wired the check into CI. If the project writes that way, write that way too; if it does not, do not impose it.

Common mistakes

A first line the length of a paragraph: GitHub and other sites cut it off around 72 characters, and the end of the thought disappears. A body that retells the diff ("changed three lines in the file") instead of giving the reason. Past tense mixed with the imperative from commit to commit: pick one form and stay with it, and in someone else's project follow what is already there. A typo in the last message is fixed by git commit --amend, as long as the commit has not left for the server yet.

Where this is in the book

The full treatment is in Chapter 7. How teams actually use git. Next to it, git commit and git log are worth a look.

To practise it by hand, take the interactive lesson Three areas and a commit.