How to avoid being hated for your Git commit messages

If you’ve been writing code long enough you’ve hopefully come across version control; a thing designed to make everyone’s lives easier by providing a log of code changes in a repository — when, what and who.

When you “commit” code changes you have an opportunity to also leave a message to summarise what it is you actually did. Not only does this make it more obvious that the 5 file changes contained in this commit are to, “fix the broken transaction logger” for example, but it’s easier to scan a list of summaries than look through every file and try to understand the changes. This doesn’t just help you, it helps those of your team and those who take on the project long after you’ve forgotten about it.

So why on Earth would you under-utilise this useful area? I’m talking about the vague, nondescript messages such as “WIP” or “Update” or even, “Fixes the thing that was broken.”

If you haven’t come across these yet, you’re lucky. If you have, I feel for you. And if you’re one of those people, you should definitely read on.

Equally, it’s always a good idea to keep your commit messages on-point and whatever you do, do not criticise a client. I worked on a project once where this happened, and the client had the project handed to them. Some beady-eyed human spotted a not-so-pleasant commit message… I can tell you, it did not go down too well.

So what makes a good message?

Generally something short and to the point. Not so long that it feels like you just picked up the latest novel by Dan Brown, but long enough that Steve can come along and have a good idea of what the changes mean.

Some examples:

• “Make address fields on booking form required”
• “Send contact and valuation enquiries via email”
• “Don’t allow blank API key in check middleware”

If you’re using a project management tool such as JIRA, Pivotal Tracker or Asana, you may have a ticket reference number you can add to the commit message. E.g.

“ABC-3451 Don’t allow blank API key in check middleware”

Not only is this message relatively clear on what it is it’s doing, but you can refer back to the ticket reference to get more context on why the changes were made in the first place. It can be helpful in cases where to explain the context of the change would take too many characters in the commit message, making them difficult to read if you’re viewing the commit history on a command line.

However, if you really are the kind of person who likes to write a novel about your latest escapade into the depths of that payment gateway code, it goes into the body. Many graphical Git clients will provide you with a separate input field for this, but if you’re committing on the command line, your message subject goes first, then a blank line, then your novel.

What about other ways of tagging?

You may have build or analysis tools that are assisted by the contents of the commit message. In one project I was asked to highlight whether the commit was for a feature or fix and you can do that really easily:

“ABC-3451 [fix] Don’t allow blank API key in check middleware”

You could use branch names to communicate the same thing and eliminating the need for tagging the commit messages, e.g.

fix/abc-3451-no-blank-api-key

feature/abc-3763-send-contact-valuation-via-email

While this is a great way to help keep your branch names relatively tidy, when you merge and delete the branch you lose this context.

Is there a right or wrong way to commit my work?

Absolutely not — if there was a set standard, version control systems would most definitely enforce them through tooling. There’s etiquette but this is not the same thing. As long as you are providing a good understanding in relatively short order of what the change is for, and if necessary how to get more information on it, who am I or literally anyone else on the Internet to tell you otherwise?

The only two “rules” I would advocate:

• Never write “Update”, “Fixes” or “WIP” again (unless it’s accompanied with some context)
• Try to make sure you and your team work to a convention that keeps things consistent and works for you.