Writing Consistent Commit Messages is Not a Cliché
Tagged with Git
Last time I was doing a
git commit, I remembered the many websites I read about writing consistent commit messages.
Adam introduced me to git-cop, which aims to help us to write better commits, using Git hooks. But even using such a tool, what makes a good commit message? Should we use the past tense, should we use the third person? Should we use the imperative? Should we painstakingly explain every detail?
Here are some commit messages that come to my mind, assuming I'm fixing a bug in the page XYZ:
1 - Use the third person and the present tense: “Fixes the bug in page XYZ.”
2 - Use the imperative: “Fix the bug in page XYZ.”
3 - Use the past tense: “Fixed the bug in page XYZ.”
4 - Use the gerund: “Fixing the bug in page XYZ.”
Which option would you use? Pick one; we will discuss each option below. These three options are widely used on Git repositories; I’ve used all of these three options at various times.
We are trying to say: "This commit" → "fixes the bug in the page XYZ." For me, it makes sense.
Using imperative matches commit commands like merge and revert that are default in Git. This seems potentially a good practice.
We can imagine the commit list as a log, and everything that’s been completed was in the past. "This commit' → "fixed the bug in the page XYZ."
You can also imagine:
"I/We" → "fixed the bug in the page XYZ."
To me, this also makes sense.
When we use the gerund we are trying to say "I am doing this." The problem with this approach is that when it’s read as a log, the ongoing tense of the gerund seems out of place. Also, the gerund costs us three characters (-ing) in each instance.
If we check the commits made by Linus Torvalds, we can see examples of good commit messages.
Reading his commit messages, we can see he uses the imperative.
He adds a short description explaining the commit’s purpose.
It's really instructive to see those. Looking at these commits I felt ashamed about some of my own previous commits.
There is no “best approach.” I think this is something more personal. Make sure to talk with your team to see if some trends have already naturally emerged in their commit messages.
Personally, I think Torvalds’ approach is awesome. I tend to prefer the imperative, and I find myself using it the most nowadays. However, I still occasionally use all the other styles, especially the third person, but I try to make it the most consistent I can, using only one approach, the imperative.
What do your commit messages look like? What was your last commit message?
Software Engineer with experience working in multi-cultural teams, Franze wants to help people when he can, and he is passionate about programming and Computer Science. Founder of RemoteMeetup.com where he can meet people all over the World. When Franze is not coding, he is studying something about programming.