How to Write a Great Commit Message

So annoying.
Fixed a bug!
Hope I never see this again.

These are not great commit messages; in fact, they are nearly worthless. A great commit message should tell the reader all they need to know about the what of the commit. They should only have to look at the actual diff of the commit to see how it was accomplished.

Anatomy of a Great Commit Message

Think of a commit message like an email:

  • It contains your contact information. You don't even have to do anything; you get this for free!
  • It should have a subject: the shorter, one-line summary.
  • A body: the detailed description.

All commit messages should abide by the following criteria:

  • Begin with a one line summary. It should be capitalized and succinct (50 chars or less).
  • This should be followed by a longer description, if necessary.
  • The first two items should be separated by an empty line.
  • All lines should be wrapped at approximately 72 characters.
  • Reference an issue in your commits whenever possible. If using GitHub issues, you can reference them by using 'gh-80' for issue '#80'. If your commit completes the issue, you can use a number of terms to close the issue, such as: 'Closes gh-80'.
  • If you forget to reference the issue in your commit, and the commit has already been pushed, reference the commit's hash in a comment on the ticket.

Here is a model Git commit message as written by Tim Pope in his post from 2008:

Capitalized, short (50 chars or less) summary.

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body. The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines.

* Bullet points are okay, too.
* Typically a hyphen or asterisk is used for the bullet, preceded by a
single space, with blank lines in between, but conventions vary here.
* Use a hanging indent.

Closes gh-80.

The majority of your commit messages may be much simpler than the example above, but pick and choose the appropriate elements. Here is an example more common to the real world:

Fix for editor dashboard showing incorrect date.

* Fixed date calculation logic.
* Added function docblock to comply with coding standards.
* Refactored foreach loop, improving clarity.

Closes gh-80.

With just a few small improvements to your commit messages, your fellow developers, and your future self will surely thank you!