Git Commit Message Etiquette

01 May 2018

Photo: Unsplash

Git has now been a de facto tool for developers. It has powered the awesome adoption of OSS and was the second well-known project from Linus Torvalds.

One of the things I look out for when looking at a projects repo is the standard of the git commit messages. It can sometimes tell you a lot about the developer(s) and the culture of the project.

It is easy to not give a great deal or thought to the commit messages you add to commit your code. This is especially true when committing in a high frequency as highlighted in the xkcd cartoon:

Now while your code should be self-documenting, your git commit log should explain what was done and when. It can be used to provide context to the commits and should be read like a history book of your project.

But, sometimes in the real world, we don’t care enough or are in a rush. Commit messages such as the following (taken from a project I am involved in) offer no value:

If we take the first log entry, I have so many questions. What method? Why are we now returning an empty list? What was returned before? That line was all that was included in the commit message. There was no extra content providing any insight. In order for me to see what was done, I need to diff the change. That takes time and I will still not be any wiser on why it was done.

I am not going to rehash how to write awesome commit messages or why it is important. Chris Beams has written the only article needed on it and I try to follow his recommendations.

The impact is your git log becomes a useful resource. This is even more important when your project grows or people move on. Knowledge is power and as developers, we need to know why things may have been done in a certain way. Git log should be your answers.

Let’s make a point of cleaning up our commit messages and calling out people that leave bad ones. Yes commit 227b4e11ae0824cc3a6508a990d99b4dbbed8f11 in the dotnet core repo, I am talking about you!

I’d love to hear your thoughts on this subject so please share them with me via twitter or email.

Amendment - Updated the example bad dotnet core example as when I saw it I thought back to this article.