Git commit messages

A recent post from David Thompson, My favourite Git Commit, hit the top of Hacker News today and I thought I should jot down a few thoughts.

When working on a small project alone, the details of your commit messages may not seem important but if/when that project grows, and more people join, it is useful to have consistent and well formed commit messages. If some developer is trying to understand why something is the way it is, git blame is a good place to start. If that takes them to a commit whose subject is more stuff, well that’s not going to very helpful!

What is well-formed, well lots has been written about this. The key points that I keep coming back to and try to enforce encourage my team to use are the following:

What & Why, not How

The code itself should be clear and self-explanatory (what is and isn’t clear and self-explanatory is something for another time) so we shouldn’t need to explain in the commit how it’s doing it. What may not be clear, and definitely should be in the commit message, is what it does and why it doing that.

This doesn’t have to be an essay, but it could be if that’s needed. Also this shouldn’t duplicate work. If there has been a long discussion in a Jira ticket or a Trello card, then a link to the ticket/card would be sufficient here. The GDS commit mentioned in David’s post is a brilliant example of this, complete with all the steps taken to diagnose it.

Style

Looking through a a git log should give a fairly consistent experience. The subjects shouldn’t be too long, nor too short. Somewhere between 30 and 50 characters, excluding any issue/build tags. It should also be written in the imperative mood, it should complete this sentence “This commit will …”.

Here are some bad examples:

c4fe7753 fix typo
6293a870 removing extra div
a0bd75ea report fixes
99428f3e more report fixes

And some better ones:

ca8355cf Fix the toggle class on chevrons
cf940fc2 Use firebase to attribute links correctly
334654af Fix diffInSeconds call on null
1ab3c47a Update search ranking weights

Gitmoji

I’ve been using an emoji at the beginning of calendar event titles for a long time. This allows me to scan across a weeks/months worth of events and get a quick feel for what’s going on:

• 🐔 standup (A chicken? yes, ask me why some time)
• 🖥 video conference
• 🤓 time for code review
• 📞 phone call
• ✏️ time for writing
• 👨‍👧‍👦 Pickup kids
• 📚 time for reading

I while ago I found Gitmoji. This is the same principle for git commits. Prefix your message with an emoji to give an at-a-glance summary of the change, for example:

• ⚡️ Performance
• 🔥 Removing code
• 🐛 Bug fix
• ⬆️ Updating dependancies

Squash

Sometimes when you’re ‘in the zone’ it’s easy to forget the rules guidelines and your commits end up looking like this

xkcd on git commits

There is a solution to this, before pushing these commits somewhere beyond your local repo you can squash these commits in to one. Most git client interfaces have a way to do this via an interactive rebase but it’s also fairly easy to do this on the command line, David Walsh explains here in Squash Commits with Git.