Writing good commit messages

You can think of the commit log as a newsfeed for your project, in which the log message is the headline for each commit. Have you ever skimmed the headlines in a newspaper (or, for a more current example, BuzzFeed) and come away thinking you’d gotten a summary of what was happening in the world?

A good headline doesn’t have to tell the whole story, but it should tell you enough to know what the story is about before reading it. If you’re working by yourself or closely with one or two collaborators, the log may seem attractive just for historical purposes because you would have been there for most of the commits. But in Git repositories with many collaborators, the commit log can be more valuable as a way of knowing what happened when you weren’t looking.

The seven rules of a great Git commit message

  1. Separate subject from the body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize on the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain /what/ and /why/ vs. /how/

A commit message should answer three questions about a patch:

  • Why is it necessary? Is it a bug fix, an added feature, improve performance, or be a change for the sake of correctness?
  • How does this change address the issue? For small patches, this part is not needed, but it should be a high-level description of what the approach was.
  • What effects does the patch have? This is the most critical question to answer, as it can point out problems where you are making too many changes in one commit or branch. One or two bullet points for related changes may be okay, but five or six are likely indicators of a commit that is doing too many things.

What not to do

  • SCM is not a backup system – Developers who use it as such tend to do end-of-day commits, checking in everything at the end of the day. Sending large new features in a single giant commit. Patches with hundreds of lines of code to dump a new feature into the code while at the same time rewriting half the existing infrastructure to support this feature. As a result, those hundreds of lines of code need to be reviewed every time a bug is discovered that is somehow related to that area of code. In the worst-case, this bug has also maybe already been deployed and uploaded from git in production.

  • Per-file commit – More often than not a logical change affects more than one file and it should not be split up into two commits.

  • Lazy commit messages – Any commit labeled as “misc fixes and cleanups” or similar. Mixing two unrelated functional changes makes it harder to indent if you flaws and anyone else to keep track of what’s happening in the project.

Need a simple way to do smarter deployments? Take a look at GitFTP-Deploy. Try free for 7 days.