by Adam Brett

Anatomy Of A Good Commit Message

The developers at my new job have been using subversion for the last 8 years, and with a few exceptions, huge code-bomb style commits covering numerous features and changes (and with generic one-line commit messages) seem to have been the norm. Source control was used primarily for backup (a sin I think many teams are guilty of at one point or another), and wasn't used to its full potential, so no-one really paid attention to commit messages or the size of commits; after they were written they were never referenced again.

When I joined the team, they had already researched and seen the benefits of Git and wanted to move as soon as possible. With my advocation and re-iteration of the various benefits management were quickly convinced and the work was scheduled. I wanted to make sure Git became a useful tool for the whole team and once everything was ready to be moved across, that meant introducing the idea of smaller atomic commits with better (more useful) commit messages.

There are already a few good posts and discussions about what makes a good commit message, but they all lack the rigidity that I felt we were going to need to break 8 years of bad habit. I wanted a system I could present that wasn't going to be overwhelming to a team of widely varying skill levels, on top of getting used to a new SCM, a new way of working (with feature branches/git flow) and smaller atomic commits.

Whilst the information already out there is great, it doesn't provide the copy, paste, and fill-in-the-blanks kind of template I wanted for the junior developers so they didn't have to think too much about their commit messages (at least until they became more familiar with the new tools and processes), and those already familiar with good commit practices had a rock solid base to work from.

Template

With that in mind, I compiled the various posts and discussions on commit messages into the following template, the bulk of the template is from here with a couple of minor modifications. It's widely accepted as the best example of a good commit message:

Action: 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; tools like
rebase can get confused if you run the two together.

Write your commit message in the present tense: "Fix bug" and not "Fixed
bug."  This convention matches up with commit messages generated by
commands like git merge and git revert.

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

Relation: #issue

Rules

  1. The body of a commit is mandatory. You should explain to those who might be looking back over your code why you did what you did in this commit.

  2. Commits should be atomic. That is, a single unit of functionality that can be applied or reverted in its entirety. Commits should not include changes across functionality.

  3. The first word of the summary should be one of:

* Add
* Modify
* Re-factor
* Fix
* Remove
* Tidy

And should accurately describe what you're doing with this commit.  If you're doing more than one of these actions in a commit, you should probably consider breaking them into smaller commits.
  1. The last line of the description should be one of the following statuses, followed by a hash (#) and the issue number from the tracker, if relevant:
* Fixes
* Closes
* References

Your keywords may vary, but in our issue tracker _fixes_ and _closes_ are keywords that will assign statuses to an issue, _references_ doesn't do anything, but including the issue number with a # will link the commit to that issue, so it's nice to know that you're just putting it in there to reference the issue.

These rules haven't been in use very long, and aren't set in stone. As time goes on we might find ourselves relaxing them, adding to them, or changing them all together. As a base to work from they pretty solid right now and should stand us in good stead for the foreseeable future.

For exclusive content, including screen-casts, videos, and early beta access to my projects, subscribe to my email list below.


I love discussion, but not blog comments. If you want to comment on what's written above, head over to twitter.