682

I read once that git commit messages should be in the imperative present tense, e.g. "Add tests for x". I always find myself using the past tense, e.g. "Added tests for x" though, which feels a lot more natural to me.

Here's a recent John Resig commit showing the two in one message:

Tweak some more jQuery set results in the manipulation tests. Also fixed the order of the expected test results.

Does it matter? Which should I use?

Lucas
  • 523
  • 2
  • 10
  • 20
Skilldrick
  • 69,215
  • 34
  • 177
  • 229
  • Similar question: http://stackoverflow.com/questions/1753808/should-commit-messages-be-written-in-present-or-past-tense – wip Sep 09 '13 at 02:12
  • 1
    See also http://www.exquisitetweets.com/collection/hugovk/1258 http://english.stackexchange.com/q/6602/9001 http://programmers.stackexchange.com/q/56031/25708 http://programmers.stackexchange.com/q/157590/25708 http://stackoverflow.com/q/1753808/724176 – Hugo Jun 18 '14 at 06:32
  • See also https://github.com/agis-/git-style-guide – Agis Apr 04 '15 at 16:17
  • I think it would be better to promote this to programmers.com, but now I don't have such options. – eonil Apr 23 '15 at 02:58
  • 3
    @Eonil if it's closed for being opinion based here it will be closed for being opinion based there as well. – ratchet freak Apr 23 '15 at 08:42
  • @Eonil Also, questions older than 60 days cannot be migrated (even by moderators). – yannis Apr 23 '15 at 08:46
  • My understanding is that the official preference for present-tense comes down to the concept of open-source and that the commit could potentially be pulled by anyone. To a consumer of your code the sentence "Apply X to Your Code" makes more sense than "Applied X to Your Code" – Stuart Cusack Jan 14 '19 at 00:13
  • 1
    I am not sure it's necessarily 'opinion-based'. For example if the commit messages are used for creating automated release notes, then it almost 100% of the time makes sense to have it in the latter format (ie 'xyz feature added'). If not then it doesn't matter so much and its an opinion-based preference. – developerinlondon Oct 22 '19 at 10:22
  • This question is probably not in its right place, but not such "opinion-based". I don't think people are really against to use grammatical messages. And why do you think you should use *a single style* in the whole message? It's ungrammatical to always use the single style for all kinds of contexts. So, I'd assume most answers here are endorsing the style used in the *summary* line of the message. Otherwise, the present tense is likely to be grammatical if it is used on the text to describe the current status of the code, but imperative forms do not unless there is an interactive environment. – FrankHB May 29 '20 at 03:38
  • Further, if the messages are in a series of (possibly reordered) patches, they can make more messes when you assume the literal meaning of the imperative forms. The use of imperative forms is more or less like side effects in the programming languages which are only well-behaved enough with some constraints in some local contexts (e.g. used only in some sane branch of reliable instance of the version history here). They do not work in general, globally. – FrankHB May 29 '20 at 03:49
  • Note that the past tense used in the summary can be treated as a form of [answer ellispse](https://en.wikipedia.org/wiki/Answer_ellipsis) with an implicit question: what did you do on your commit? This seems more grammatical to the imperative mood at least in this context. Imperative can be OK elsewhere. For commands like `git`, it is natural to use imperative mood because the user can expect the response from the interactive environment. This is simply not the case in the commit messages. – FrankHB May 29 '20 at 03:54
  • As this is [documented in `git`](https://git.kernel.org/pub/scm/git/git.git/tree/Documentation/SubmittingPatches?id=HEAD#n133), it's **not** just _opinion-based._ – CodeFinity Apr 14 '21 at 12:35
  • In West World, when merging android code, is “Added ability to murder humans” better than “Add ability to murder humans”? If I apply the merge, the first quote implies that the person that did the commit is at fault. For the second, it’s clear I want to have murdering androids. As I die, I will wonder why I wasted time on how comments are worded. – Randy in Marin Aug 03 '22 at 23:53

7 Answers7

812

The preference for present-tense, imperative-style commit messages comes from Git itself. From Documentation/SubmittingPatches in the Git repo:

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 behavior.

So you'll see a lot of Git commit messages written in that style. If you're working on a team or on open source software, it is helpful if everyone sticks to that style for consistency. Even if you're working on a private project, and you're the only one who will ever see your git history, it's helpful to use the imperative mood because it establishes good habits that will be appreciated when you're working with others.

flederwiesel
  • 447
  • 1
  • 9
  • 17
mipadi
  • 398,885
  • 90
  • 523
  • 479
  • 110
    I think this is an excellent choice. Think about what a commit is, in diff form: a set of instructions for how to go from a previous state to a new state. Just as the diff says "add this line here, remove this line here", the commit message says in qualitative terms "make this change". (Yes, git does store the commit simply as a tree with metadata, but to a human, the important part of a commit is the diff.) – Cascabel Aug 27 '10 at 03:11
  • 175
    You may see a commit as a set of instructions for how to go from the previous state to the new state; but I see it more as a check-point in the evolution of the code. For me, the commit message is a log of what has been done to the code since the previous commit; and for a log, past tense makes a lot more sense. If you really think the commit message should be a set of instructions, then the imperative tense is the way to go. I just really do not think of it in that way. – karadoc Jun 04 '12 at 14:16
  • 2
    Unfortunately my question got closed as a duplicate of this and while I understand that it is done in present tense because the Git documentation says so there is no explanation as to why. – oschrenk Jul 20 '12 at 18:03
  • 11
    @oschrenk: Later versions of the file have given a reason: "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." – mipadi Apr 10 '13 at 07:21
  • 2
    +1 for the reference. It would be nice if @mipadi's comment were included. – l0b0 Apr 24 '13 at 13:32
  • 69
    The commit message should be imperative, present tense because with git you or somebody else may end up doing `rebase` or `cherry-pick` and in that case, the commit may be used outside its original context. As a result, the commit message should be written standalone without expecting reader to view any surrounding commit messages. When you're cherry picking patches, it makes more sense to apply "Fix quicksort algorithm" or "Sorting: Improve performance" instead of "Fixed bug #124" or "Modified sorting to improve performance". – Mikko Rantalainen May 06 '13 at 07:22
  • 11
    The way I think about this is that the message should tell me what will change if I choose to apply this commit to my branch. I don't think of it as a log but as states that I can move to and I need to know what will happen when I choose a particular state. – steinybot Nov 07 '13 at 23:21
  • 5
    When I see the log before checking out, the imperative makes me feel like that's what I should do after checking out whereas the past tense makes me feel like that was what was done for the commit. – funct7 Jan 05 '16 at 06:45
  • My +1 for "it does not matter" for the case when repository is not to be heavily shared. The argument for the *past tense* could be that generating a report "what was done last month by that person" or "Changes from the last version" via `git log` may be more important sometimes than rebasing or cherry-picking. – pepr Jan 19 '16 at 15:02
  • The linked page doesn't have this information anymore. Is that still the case? – kenorb Jun 13 '16 at 11:29
  • 1
    @kenorb: It does. It's on Line 117. – mipadi Jun 13 '16 at 16:25
  • 3
    But the commits are in the git history, and history is in the past! – Iulian Onofrei Oct 03 '16 at 11:49
  • 7
    I almost upvoted this answer, but I think "the git project itself recommends it" is not a good enough reason. I don't really care either way (imperative or past-tense), only that it should be consistent within the project. This answer would be great IMHO, if it gave a better explanation *why* imperative is better than past tense. – Sybille Peters Dec 22 '17 at 12:13
  • 3
    @MikkoRantalainen: `"When you're cherry picking patches, it makes more sense to apply "Fix quicksort algorithm" ... instead of "Fixed [quicksort algorithm]"` Why? – Sinjai Jan 24 '18 at 01:52
  • @Sinjai you are applying fixes/patches, not history states. If commit message says "Fixed ..." it usually refers what the original developer did, not what the patch actually does to the project. In long run, the commit history will make more sense if commit messages describe what cherry picking a given commit will do if applied to different branch. – Mikko Rantalainen Jan 27 '18 at 17:19
  • 1
    @MikkoRantalainen what's the difference between reading it as "this patch fixed a bug" and "this patch fixes a bug"? "I want to include this commit which fixed bug #204" vs "I want to include this commit which fixes bug #204"? – Sinjai Jan 29 '18 at 01:36
  • 2
    Commits are events because it represents something that has happened in the repo (and the event sourcing would modify the filesystem accordingly when checking out a specific changeset). Therefore writing them in past makes more sense. If you interpret commits as commands then write them in present, but commands represent intentions that could be carried out or not. Whichever you choose, stick with one. – diegosasw May 23 '18 at 09:28
  • 1
    I don't understand why the 3rd person present is not OK for commit messages. "Adds Action menu to the menubar" "Fixes Apply button to toggle when icon is selected" Why aren't any of these OK? And for the `rebase` and `cherry pick` arguments: why isn't the 3rd person present OK for this? – WhyWhat Mar 22 '20 at 18:58
  • 1
    Downvote for the false declaration. To be clear, Git does use imperative style in the project, but the tool itself does not enforce it. And as others have answered, this style does not "comes from Git itself". It has a long history. – FrankHB May 29 '20 at 03:22
  • 3
    "*Comes from git itself*" is an extremely poor argument. So if git was doing it wrong for whatever reason, everyone else has to do do it wrong as well? As Bertrand Russell once said "*Even if everyone agrees, everyone can be wrong.*" I'm missing a real argument here, why imperative is better than alternatives. – Mecki Jan 17 '21 at 14:54
  • Updated reference: https://kernel.googlesource.com/pub/scm/git/git.git/+/74cc1aa55f30ed76424a0e7226ab519aa6265061/Documentation/SubmittingPatches#181 – solimant Mar 18 '22 at 19:51
  • I agree with that you can (re)play them and much more projects these days have imperative style [https://groups.google.com/g/django-developers/c/GCtDoW2rh54/m/BxnnHJEFBgAJ](https://groups.google.com/g/django-developers/c/GCtDoW2rh54/m/BxnnHJEFBgAJ) _Commit message is not a history record. Commit is a diff, and commit message should be a human version of that diff. Please keep in mind that commits can be (re)played in both direction to do/undo changes. So, it is actually more readable to use the imperative/indicative mood, because you expect it to match the meaning of diff._ – S. H. Oct 20 '22 at 14:02
  • Past tense for git commits and I guess imperative can be used for pull request titles since it's what merging those commits will do. – BrunoElo Jan 08 '23 at 02:44
429

Your project should almost always use the past tense. In any case, the project should always use the same tense for consistency and clarity.

I understand some of the other arguments arguing to use the present tense, but they usually don't apply. The following bullet points are common arguments for writing in the present tense, and my response.

  • Writing in the present tense tells someone what applying the commit will do, rather than what you did.

This is the most correct reason one would want to use the present tense, but only with the right style of project. This manner of thinking considers all commits as optional improvements or features, and you are free to decide which commits to keep and which to reject in your particular repository.

This argument works if you are dealing with a truly distributed project. If you are dealing with a distributed project, you are probably working on an open source project. And it is probably a very large project if it is really distributed. In fact, it's probably either the Linux kernel or Git. Since Linux is likely what caused Git to spread and gain in popularity, it's easy to understand why people would consider its style the authority. Yes, the style makes sense with those two projects. Or, in general, it works with large, open source, distributed projects.

That being said, most projects in source control do not work like this. It is usually incorrect for most repositories. It's a modern way of thinking about a commits: Subversion (SVN) and CVS repositories could barely support this style of repository check-ins. Usually an integration branch handled filtering bad check-ins, but those generally weren't considered "optional" or "nice-to-have features".

In most scenarios, when you are making commits to a source repository, you are writing a journal entry which describes what changed with this update, to make it easier for others in the future to understand why a change was made. It generally isn't an optional change - other people in the project are required to either merge or rebase on it. You don't write a diary entry such as "Dear diary, today I meet a boy and he says hello to me.", but instead you write "I met a boy and he said hello to me."

Finally, for such non-distributed projects, 99.99% of the time a person will be reading a commit message is for reading history - history is read in the past tense. 0.01% of the time it will be deciding whether or not they should apply this commit or integrate it into their branch/repository.

  • Consistency. That's how it is in many projects (including git itself). Also git tools that generate commits (like git merge or git revert) do it.

No, I guarantee you that the majority of projects ever logged in a version control system have had their history in the past tense (I don't have references, but it's probably right, considering the present tense argument is new since Git). "Revision" messages or commit messages in the present tense only started making sense in truly distributed projects - see the first point above.

  • People not only read history to know "what happened to this codebase", but also to answer questions like "what happens when I cherry-pick this commit", or "what kind of new things will happen to my code base because of these commits I may or may not merge in the future".

See the first point. 99.99% of the time a person will be reading a commit message is for reading history - history is read in the past tense. 0.01% of the time it will be deciding whether or not they should apply this commit or integrate it into their branch/repository. 99.99% beats 0.01%.

  • It's usually shorter

I've never seen a good argument that says use improper tense/grammar because it's shorter. You'll probably only save 3 characters on average for a standard 50 character message. That being said, the present tense on average will probably be a few characters shorter.

  • You can name commits more consistently with titles of tickets in your issue/feature tracker (which don't use past tense, although sometimes future)

Tickets are written as either something that is currently happening (e.g. the app is showing the wrong behavior when I click this button), or something that needs to be done in the future (e.g. the text will need a review by the editor).

History (i.e. commit messages) is written as something that was done in the past (e.g. the problem was fixed).

Matt Quigley
  • 7,614
  • 4
  • 25
  • 26
  • 120
    I first heard today about the supposed preference for imperative style commits. To me, it sounded so unnatural and bizarre that I decided to seek some more opinions. I'm pleased to see I'm not the only one who thinks past tense is more natural for commit messages. :) – karadoc May 23 '12 at 00:25
  • 78
    git's automatically generated merge and rebase commit messages are imperative and present tense ("Merge", not "Merged"; "Rebase", not "Rebased"), so you might want to match this in your own commit messages for consistency. – mjs Apr 16 '13 at 16:51
  • 20
    Seems that the difference is between a focus on the change to the *software* - "Fixed X by doing Y" - or the *repository* - "Do Y to fix X." +1 for a good argument, but I think the repo should usually focus on itself rather than the resulting software. – l0b0 Apr 24 '13 at 13:40
  • 35
    The thing is, using imperative, present tense works for huge projects (e.g. Linux) so it obviously scales. In addition, it requires pretty much zero effort using over past tense. As result, I see no reason (other than "old people are used to write commit messages in past tense") to use anything else but imperative, present tense. If you can learn the git command set, you can learn writing in imperative, present tense. – Mikko Rantalainen May 06 '13 at 07:28
  • 48
    Imperative is not "new since git". ChangeLog existed long before git, and the use of imperative has always been the recommended style in the GNU Project. http://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html – adl Jul 16 '13 at 09:44
  • 8
    @adl In the very next example, http://www.gnu.org/prep/standards/html_node/Simple-Changes.html#Simple-Changes, the past tense is used: "All callers changed" It would be an exaggeration to say there was never imperative tense, but it was certainly less common. – Matt Quigley Jul 17 '13 at 18:34
  • 5
    I'm skeptical of the claim that people spend 99.99% of their time reading commit messages only to review history and not to decide how to apply a commit to their commit tree. The argument would be stronger with actual empirical facts and evidence to back it up. –  Jul 25 '13 at 04:40
  • 3
    @Cupcake I agree it would be stronger with evidence but not sure where to get it. I'm believe, but I don't have data, that almost all software projects are meant to be taken as a whole, or at least a whole particular branch. It's quite feasible for someone to start at a branch and experiment with someone else's changes by cherry-picking, but I strongly believe that scenario happens less than 1/10,000 times. Most are trying to figure out what happened. I can't imagine any software, open-source or commercial, which is released by making cherry-picks instead of branches. – Matt Quigley Aug 12 '13 at 21:52
  • 7
    Imperative commit comments sound like Chinglish to me. I think any native English speaker will think in the past tense when describing changes that they *made*. – Andy Jul 13 '15 at 21:03
  • 1
    In our team, we commit in our develop branch..using present tense in our commit makes sense to our Team Lead to merge the changes in master... – LC 웃 May 19 '16 at 09:38
  • 10
    The 99.99% assertion is not true for teams that do code review. Most of the time when I read a commit message, it's during code review, **before** the commit is applied. Hence, imperative tense makes sense. – djsmith Jun 30 '17 at 16:35
  • 2
    If you are familiar with DDD systems, Git or any source control repository fits exactly with the approach that "events should be written in past". A commit is something that has already occurred in a repository. It should be immutable and therefore it's like an event (in past). If we write it in present, it's more like an intention (a command), which could have an effect in the system OR NOT (it could be rejected). If you checkout a specific commit, the historical of the previous commits would be applied one by one in your filesystem (like event sourcing). Present does not make sense. – diegosasw May 23 '18 at 09:13
  • 3
    If you look closely, in the GNU coding standards they always use the past tense when describing what was done. The present tense is used to describe what the *code* now does. I always write ChangeLog entries (mine are more verbose than RMS's) and then use those for commit messages. I use the past tense. – markgalassi Aug 24 '18 at 11:59
  • 1
    I downvoted this answer. And here another link in support of the imperative mood: https://chris.beams.io/posts/git-commit/#seven-rules. – Nikos Alexandris Feb 25 '19 at 14:12
  • 3
    I too downvoted this answer. It's low quality. It spectacularly [begs the question](https://en.wikipedia.org/wiki/Begging_the_question). "when you are making commits to a source repository, you are writing a journal entry which describes what changed with this update". It also invents statistics ("99.99% of the time") and other facts which demonstrate a relative ignorance of the topic ("the present tense argument is new since Git", "I guarantee you that the majority of projects ever logged in a version control system have had their history in the past tense (I don't have references...)" – Pete Montgomery Mar 08 '19 at 12:52
  • 1
    The official git documentation (https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project) says to use imperative mood for the verb in the commit message, and in their example they don't end the message with a period. From that link: "Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug."" – dcp Feb 04 '21 at 13:18
  • 3
    Almost every industry/commercial project I've worked on has used past tense as a standard, as it's the most sensible way to describe what was *done*. In my experience, you're correct in stating that 99% of the time a commit message is read in the context of the history of changes, not pull requests (which are largely an open-source development paradigm). – Extragorey Aug 13 '21 at 02:38
  • 2
    I think the point made by markgalassi should be incorporated into the answer. Having commit messages align with release notes is one of the strongest points in favor of using past tense. Personally, I always use present tense because it is more common, but when I translate commit messages to release notes I wish they used the same tense. – ws_e_c421 Jan 23 '23 at 20:48
98

I wrote a fuller description on 365git.

The use of the imperative, present tense is one that takes a little getting used to. When I started mentioning it, it was met with resistance. Usually along the lines of “The commit message records what I have done”. But, Git is a distributed version control system where there are potentially many places to get changes from. Rather than writing messages that say what you’ve done; consider these messages as the instructions for what applying the commit will do. Rather than having a commit with the title:

Renamed the iVars and removed the common prefix.

Have one like this:

Rename the iVars to remove the common prefix

Which tells someone what applying the commit will do, rather than what you did. Also, if you look at your repository history you will see that the Git generated messages are written in this tense as well - “Merge” not “Merged”, “Rebase” not “Rebased” so writing in the same tense keeps things consistent. It feels strange at first but it does make sense (testimonials available upon application) and eventually becomes natural.

Having said all that - it’s your code, your repository: so set up your own guidelines and stick to them.

If, however, you do decide to go this way then git rebase -i with the reword option would be a good thing to look into.

Abizern
  • 146,289
  • 39
  • 203
  • 257
  • 12
    Well, you've mixed up two different guidelines: the Git open source project, and regular usage of Git. The provided link *does not mention tense at all*. The official Git doc only mentions the 50 char limit. _Git is a distributed VCS where there are many places to get changes from...consider these messages as the instructions for what applying the commit will do._ This only applies to a few projects which are actually distributed projects. 99.999% of Git commits will never be manually applied such a manner. In most projects, the history is a change log, which should be in the past tense. – Matt Quigley Apr 17 '13 at 00:27
  • 4
    "and should skip the full stop" – takeshin Jul 16 '13 at 08:28
44

Stick with the present tense imperative because

  • it's good to have a standard
  • it matches tickets in the bug tracker which naturally have the form "implement something", "fix something", or "test something."
Craig P. Motlin
  • 26,452
  • 17
  • 99
  • 126
22

Who are you writing the message for? And is that reader typically reading the message pre- or post- ownership the commit themselves?

I think good answers here have been given from both perspectives, I’d perhaps just fall short of suggesting there is a best answer for every project. The split vote might suggest as much.

i.e. to summarise:

  • Is the message predominantly for other people, typically reading at some point before they have assumed the change: A proposal of what taking the change will do to their existing code.

  • Is the message predominantly as a journal/record to yourself (or to your team), but typically reading from the perspective of having assumed the change and searching back to discover what happened.

Perhaps this will lead the motivation for your team/project, either way.

wardw
  • 776
  • 9
  • 18
14

does it matter? people are generally smart enough to interpret messages correctly, if they aren't you probably shouldn't let them access your repository anyway!

Michael Baldry
  • 1,990
  • 2
  • 14
  • 28
  • 43
    To [some people](https://github.com/torvalds/linux/pull/17#issuecomment-5659970), things like that matter quite a bit. – Wesley Murch May 14 '12 at 17:31
  • 3
    @mog the link does not make any statement about present and past. – ceving Mar 19 '13 at 14:49
  • 2
    If the project does scale big time the people doing code review and bug hunting will see so many commits that they need all the help you and I can provide. There's no point saving a couple of seconds now to cause major headache in the future for not writing a proper commit message. – Mikko Rantalainen May 06 '13 at 07:31
  • I'm not saying don't write a good commit message. I'm saying it doesn't matter if you use past or present tense. – Michael Baldry Oct 08 '18 at 08:20
  • 1
    How would you know, that the person not being able to interpret your commit message, is cause of that person not capable enough, or you not capable enough of writing a good commit message? – Haris Feb 22 '19 at 17:57
  • It's about mental energy. Over the course of multiple projects throughout a day, the less cognitive load we can create - here, that means being consistent with our messages - the better. It's a bit like 'perf matters' - well, good habits and consistency help when 'cognitive loads matter.' – CodeFinity Apr 18 '20 at 17:34
11

It is up to you. Just use the commit message as you wish. But it is easier if you are not switching between times and languages.

And if you develop in a team - it should be discussed and set fixed.

Andreas Rehm
  • 2,222
  • 17
  • 20