Writing Good Git Commit Messages

There are plenty of articles out there about writing good commit messages for Git, and version-control systems in general. But blogs like mine are nothing if not redundant. So as someone who deals with patches from other developers, particularly on projects like php-mode, I would like to contribute my own advice about writing good commit messages to the sea of existing information already out there.

A Non-Exhaustive List of Tips

  1. Begin with a single sentence explaining the general purpose of the patch. For example: Use "magic" comments in PHP files to simplify indentation testing.

  2. Then add a blank line between the first and any additional content. This creates better looking output for many Git tools.

  3. If the patch is fixing a bug then explain the circumstances leading to the bug, like so. This helps other developers understand the context of the patch so that they can more easily follow the code and find any potential mistakes.

  4. Even if the purpose of the patch seems self-evident from the first line it never hurts to further describe why it helps or what additional benefits the patch provides.

  5. When possible, reference relevant material to help justify the patch and provide further context for other developers.

  6. Code should be written so that it answers the question ‘How?’ as best as possible. Commit messages, on the other hand, are a great place to answer ‘Why?’ the change is necessary.

  7. If the commit reverts a previous patch then explicit reference the old patch. In my experience using the first eight digits of a commit hash is ‘unique enough’ for Git tools to create links to the commits, such as what GitHub does.

  8. Always err on the side of being too verbose instead of being too terse. I believe it is beneficial for a commit message to have too much information than to have too little.

  9. Write clear, correct sentences. Write commit messages with the attitude that you are writing high-quality documentation. This means do your best to avoid typos. Use correct punctuation. Follow all of those dull rules about writing you had to learn in high-school.

For great examples of these tips, and more good practices, I suggest reading commits for the Linux kernel. That project holds commit messages to a rather high standard and so you will see quality messages there. And of course my advice is for commits intended for other developers or the public at large. When working privately on your own local branches I believe it’s perfectly alright to have commit messages like, “WIP fixing rendering bug.” Just make sure you go back and rewrite the message later.

Obviously this is only my advice, and I do not claim these to be absolute, perfect rules. Experience working with other developers is the best way to learn how to write better commit messages. So involve yourself in projects and treat commits as a way to learn how to improve your communication skills, something that we programmers often neglect unfortunately—documentation anyone?

Advertisements

Add Your Thoughts

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s