Writing better Git commit messages

September 27, 2016 | Web Development

Using Git is a crucial part of most developers’ workflows, and so is writing committing messages for the changes they make. As a newer developer, I did some research into what make a good commit message and how I can improve my commits. Having clear, concise, and sufficiently detailed messages in critical when working on a project and even more so when working with other developers.

In this posts, I’ll share with you some of my tips for writing better Git commit messages. I’ve included my sources at the bottom, which I strongly urge you to check out for more information.

1. The most significant way to improve your commits is to improve their content.

Generally, messages should start with a single line limited to about 50 characters. This subject line should describe the changes concisely and be followed by a more detailed explanation (separated by a blank line). This can be done by using git commit instead of git commit -m. When writing a commit, answer the following questions:

– Why is this change necessary? This tells other people who review your pull request what to expect in the commit and identify and point out unrelated changes.

– How does this change address the issue? Describe, at a high level, what was done to address the issue. Example:

– What side effects does this change have? Lots of side effects may indicate you’re changing too many things, in which case you should consider splitting them up.

Tim Pope has an excellent Git commit message template:

2. Use a custom git commit template.

Don’t use git commit -m for large commits. Instead, use git commit and write a full, well thought out commit. You’ll need to establish a default editor for writing commit messages.

I prefer to use a custom template for this (see below). Save it in your user directory:

3. Create an alias for accessing the full commit logs.

The regular logs retrieved by git log lack all the information you’ll need if you’re reviewing commit history in depth. Running git log --pretty=fuller is a pain, so I created a simple alias to save me some keystrokes:

4. A properly formed commit subject line should always be able to complete the following sentence:

If applied, this commit will your subject line here

Meaning, you should write your commit message in the imperative.  Eg “Fix bug” and not “Fixed bug” or “Fixes bug.”

Hopefully these tips help you start writing better git commit messages! For more info I recommend you check out the resources I used, as they have a lot of other great details and tips.

Resources:

5 useful tips for a better commit message

Writing good commit messages

The art of the commit

 

A not about Git commit messages

And of course, you can always read the Git Pro book.

Leave a Reply

Your email address will not be published. Required fields are marked *