Writing Consistent Commit Messages is Not a Cliché


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.

When we use the third person:

We are trying to say: This commitfixes the bug in the page XYZ. For me, it makes sense.

When we use the imperative:

Using imperative matches commit commands like merge and revert that are default in Git. This seems potentially a good practice.

When we use the past tense:

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/Wefixed the bug in the page XYZ.

To me, this also makes sense.

When we use the gerund:

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.

Instructive Commit Messages

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.

The Best Approach?

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?