Why Commit Messages Suck and 6 Ways to Make Them Better

Problem: You are debugging some code and you think “What on earth was I thinking when I wrote that?”

You turn to git blame (fun fact: SVN had the command ‘praise’ as an alias to ‘blame’) to see what the last commit message was for that line:

Author: Edwin van Beinum<edwin@myemail.com>
Date:   Tue Aug 19 14:00:11 2014 -0400

Various bug fixes

You find a commit message that tells you absolutely nothing. Since this very problem bit me last week, I’ve been thinking about how to write useful commit messages. Here are six guidelines that I think will help.

One commit should do one thing

Author: Edwin van Beinum<edwin@myemail.com>
Date:   Tue Aug 19 14:00:11 2014 -0400

Fix header bug and update footer content

If your commit message has the word ‘and’ in it, you probably want to split that into two commits.

The message should explain why you made the changes

Don’t explain the code, explain the intent. If you want to know what the changes were then you can use git show and that will show you exactly what changed. Knowing why a change was made will hopefully help you figure out that mysterious code when you look at it again in six months’ time.

Author: Edwin van Beinum<edwin@myemail.com>
Date:   Tue Aug 19 14:00:11 2014 -0400

Fix title alignment

Another developer should be able to recreate your patch from the commit message alone

Author: Edwin van Beinum<edwin@myemail.com>
Date:   Tue Aug 19 14:00:11 2014 -0400

Center header title on small screen devices

Use the present tense

This is a personal preference but I think it makes it more readable and the git log reads like a sentence. “What does commit 4e8ad9d do? “ 4e8ad9d - Centers header title on small screen (2 days ago) <Edwin van Beinum>

Also, commits can be changed, using the past tense makes them sound like they are set in stone

Author: Edwin van Beinum<edwin@myemail.com>
Date:   Tue Aug 19 14:00:11 2014 -0400

Centers header title on small screen devices

Format your commit messages consistently

Use a summary in 72 chars and then double line break and add more detail if necessary

Author: Edwin van Beinum<edwin@myemail.com>
Date:   Tue Aug 19 14:00:11 2014 -0400

Centers header title on small screen devices

* devices less than 430px wide

Don’t mix reformatting commits (changing the whitespace) in with code changes

Not only does it make the diff difficult to read but if you need to revert the code changes then you probably don’t want to revert the formatting changes too.

Finally...

One of the unexpected benefits I’ve found from following these guides is that it has improved my focus and workflow; instead of rushing around trying to do everything at once, I now have a deliberate, methodical way to work through my tasks, and a nice commit history to match.

To finish, a couple of extra tricks I like to use: Use git add -p to review all changes before adding them to a commit. You can also use it to only add certain changes to a commit. Read more about it in the Git docs.

Make a Git alias for git lg to

git log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative 

which will give you a nicely formatted view of the git log.