Victor is a full stack software engineer who loves travelling and building things. Most recently created Ewolo, a cross-platform workout logger.

The case for single character git commit message prefixes

A while back I came across a really powerful method on writing git commit messages: prefix each commit with a single character to indicate what type of a change it is.

Before I can present this however, if you already haven't read the article on how to write a good commit message by Chris Beams, please do so first. The article clearly makes a case for a sane git history and lists out 7 golden rules to writing a commit message:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

In one of my previous teams, we tried to follow the above guidelines but ran into some trouble due to the fact that a majority of the members were non native english speakers. The biggest issues that we struggled with were limiting the subject line and knowing how much information to put into the body vs the subject. Moreover, the choice of verbs radically differed from one person to another, e.g. whereas I would write something like "Add authentication to item routes", a colleague might enter "Refactor item routes".

A must-read for anyone using source control

To enable people getting on the same page, prefixing each commit with the intention of the change can be a very powerful aid. Here are the proposed prefixes:

  • B, indicates a bugfix.
  • F, indicates a feature or a change - this will most likely be the majority of the commits.
  • a, code formatting change.
  • c, comments and or documentation.
  • D, dependency updates.
  • R, code refactoring, note that this is different from r below.
  • r, proven code refactoring - this is the original meaning of the mathematical term refactoring, where it can be mathematically proven that the code change does not change any functionality (I'm personally not sure where this is useful).
  • T, test cases and/or test improvements - I believe that tests should ideally live with the source code and be treated as such. However, I can see the need for this in larger code bases with a separate QA team.
  • !, unknown - i.e. for when you really need to make that commit because there's a horde of zombies waiting outside.

Given the above, our hypothetical commit examples now look like the following: "F add authentication to item routes" and "F refactor item routes" since it is a feature addition1. Most importantly, looking at the commit history, we can clearly see what commits induced changes and of what type. Also note that small case prefixes are reserved for instances where there are no changes to functionality.

To conclude, while this definitely does not replace the guidelines for writing git messages, it is a low friction change which enhances the subject line with more context :)

1 knowing my previous team it is very likely that we would still argue about whether this was a feature or a refactoring but I'm pretty sure that we would be able to settle on F eventually!

HackerNews submission / discussion

Back to the article list.