Git Commits: Past or Imperative?

09 July 2017 - Git

Up until about six months ago, all my commits have used past tense. For example, I'd write "Added ...", or "Fixed ...", etc. However, at my current contract, they have a standard where the commits use imperative tense, eg. "Add ...", "Fix ...", etc.

At first, this felt very unnatural. It obviously wasn't a biggie though, and I'm a strong believer that consistency in a codebase is MUCH more important than an individual's personal preference/habit.

All the previous companies I've worked for during twenty years of development happen to have used past tense, and I somehow seem to have missed how commonly used imperative is! Then I saw a couple of commits by fellow .NET Oxford co-founder Matt Nield in a shared repo we were working for .NET Oxford which also used imperative tense. This made me wonder if using imperative tense is actually more widely used than I had thought. So I Googled it, and surprise surprise it turns out that Git themselves use imperative for their codebase, and this is their preferred way of writing commits! ...

Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour.

I then looked through a few Github repositories, and it looks like imperative is used there more often than not too (as least from the repos I looked at). So out of interest, I posted a poll on Twitter ...

Out of curiosity - what tense do you write #Git commit messages? Seems that imperative is recommended by Git, but it feels wrong! (IMO)
— Dan Clarke (@dracan) February 7, 2017

I should point out that my comment in that tweet "but it feels wrong (IMO)" no longer applies, but we'll get to that shortly.

The results show that past tense is preferred out of the 81 developers who voted. However, that is obviously a very small sample of developers. What was more interesting were the replies I got after the tweet. It also prompted me to do a bit more reading into different people's reasons behind their preference.

The biggest reason I found for using imperative tense was along the lines of ...

@dracan @CodingBlocks I use imperative because it tells me what that commit accomplishes, not what the developer has done.
— K. Hoodlet (@andMYhacks) February 7, 2017

But I'd argue that if this was the reason, then surely the commit should be phrased "Adds ...", and not "Add ...".

This whole topic is obviously very opinion based, and this post isn't about pushing any preference, but more just an observational post after doing the poll.

I have actually now switched sides and am now also using imperative for my own projects. However, my change of preference has nothing at all to do with the tense, or the fact that it's a command rather than what the developer did - but more that I find it a lot more terse ...

imperative tends to push me to more concise messages :-)
— Stuart Leeks (@stuartleeks) February 7, 2017

I'm not only finding that my commit messages are shorter because of the shorter verb at the start, but also because now that I'm thinking about the terseness, I'm also cutting down on articles (eg. 'the') in my commit messages. So rather than writing "Implemented memcached caching against the API", I'd write "Implement memcached caching against API". I could obviously have skipped the "the" in either version, however I'm just finding that I naturally try and make the sentence even more terse when using imperative tense.

Another reason I like which was mentioned in this Stackoverflow answer, is that it more closely matches the title of the ticket in the bug/issue tracker, as tickets in trackers tend to be written before the work is done.

I'm also finding that it forces a more distinct separation between the commit's summary line and the more detailed description part, which incidentally I still use past tense for.

Summary

When it comes down to it, my thoughts are - it doesn't really matter! What matters is that it's consistent with your codebase. Your team should choose and agree on a standard, and stick to it. If you're contributing towards another project - then look at the tense that has been used so far and follow suit.

Please retweet if you enjoyed this post ...