May 16
Better Git Commit Messages
Git commit messages are really useful to other people, so it makes a lot of sense to make tham as understandable as possible. Let’s see some pointers as to what and how to write into git commit messages.
If you work with git commits, changes are you will need to search the history of changes at some point.
If git commit messages are hard to decipher, it will make your job harder, which might annoy you a lot and take you some time you could spend doing something more enjoyable or useful.
With that, it makes sense to learn a few things about git commit messages. Let’s see some good practice. I say good praactice on purpose because I don’t necessarily believe in best practice, nor I think these rules are something to follow in every situation — context exists, so consider it.
Length
There are actually two different lengths to consider. Git commit messages consist of two parts — subject and body.
Let’s have a look at this commit for example:
Rework @propertysource early parsing logicRework the @propertysource parsing logic recently changed in commit
7c60888 to deal with the same source appearing on a @configuration
class and an @import class.Processing now occurs in a single sweep, with any previously added
sources being converted to a CompositePropertySource.Issue: SPR-12115
This line:
Rework @propertysource early parsing logicis a subject line.
The rest after an empty line is a body.
When it comes to the subject line, good practice is to limit yourself to 50 characters. That’s because you want to be brief, and because this line appears in various places and when too long, it get truncated (e.g. on GitHub).
The body can contain lines wrapped at 72 chracters. You can also set up your git editor of choice in a way that it enforces this limit for you, e.g. you can put the following line into .vimrc :
filetype indent plugin onAgain, the reason is that the body might appear at some places where longer messages would not be displayed well.
Language
Make sure you don’t have unnecessary spelling mistakes in your commit messages. Or bad grammar. Or abbreviations or jargon that other people might not understand.
It’s also recommended to write the subject line in the imperative mood. That means as if you were giving orders to someone. Let’s practise:
- Add README.md file
- Refactor sendMsg() method
- Fix email template
These are all messages in the imperative mood, which is a recommended way of writting the subject line.
If you commit using the -m option of git commit , this is what to write there, so an example would be:
$ git commit -m"Add README.md file"Also, the imperative mood is recommended for the subject line only, you can relax in the body part (if that’s needed at all).
Conventional commits
It might make sense to follow something like Conventional Commits specification.
For example, there’s this rule about the subject line:
<type>[optional scope]: <description>Where type is one of many words that describe what kind of change you’re making (e.g. fix for fixing a bug, or docs for writing documentation),description might be a certain module or part of the app and it’s optional, and description describes your actual change.
I work on teams where this is followed. Then I work on different teams where this is not followed. Of course I often forget what teams follow it, so I’ve learnt to use this format all the time. I especially like the type word, it makes it quick to recognise what kind of change the commit deals with.
Explain what and why, not how
The code itself explains how, so if someone wants to know, they can read the code. Git commit messages should deal with what (the subject line) and why (the body).
Having said that, the body is a good place to include some metadata like tracking IDs, other PRs, etc. You could actually notice this in the initial example commit I shared, see the last line:
Issue: SPR-12115That’s exactly it.
Writting code is not a solitary activity, you simply work with other people. Make that easier for everybody by sticking to a few simple rules that might help other people to understand your work. Are there any other rules you and your team follow in git commit messages?
