Git commit messages
Tags: git
Published: 2019-10-21 19:44:19

---
title: Git commit messages
published: true
date: 2019-10-18 12:11:05 UTC
tags: git
canonical_url: https://www.marcroberts.info/2019/git-commit-messages/
---

A recent post from David Thompson, [My favourite Git Commit](https://fatbusinessman.com/2019/my-favourite-git-commit), hit the top of [Hacker News](https://news.ycombinator.com/item?id=21289827) 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](https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) [been](https://chris.beams.io/posts/git-commit/) [written](https://github.com/erlang/otp/wiki/writing-good-commit-messages) 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](https://github.com/alphagov/govuk-puppet/commit/63b36f93bf75a848e2125008aa1e880c5861cf46) 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](https://en.wikipedia.org/wiki/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](https://gitmoji.carloscuesta.me/). 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

![List of git commits progressively getting worse over time](https://imgs.xkcd.com/comics/git_commit.png)
<a href="https://xkcd.com/1296/">xkcd</a> 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](https://davidwalsh.name/squash-commits-git).