13

I am a developer and I am not native English speaker. When I see commits I can't understand why titles for them start with infinitive without to. For example from Spring commits

Add missing runtime hints for ProblemDetail mixins
Merge branch '6.0.x'
Fix position bug in NettyDataBuffer::toByteBuffer
Upgrade to Reactor 2023.0.0
Merge branch '6.0.x'
Consistent ordering of overloaded operations
Upgrade to Reactor 2022.0.13 and Netty 4.1.101
Introduce update variant with KeyHolder and explicit key column names Merge branch '6.0.x'
Fix wrong nullability requirement

How to explain it?
What are subject and predicate in ‘Add missing runtime hints for ProblemDetail mixins’?
I would understand if it were ‘Adds missing runtime hints for ProblemDetail mixins’ because commit were a subject and Adds were a predicate.

Could anyone explain?

Improve this question
14
  • 6
    We don't have to write lists of things to do like school essays or novels. Buy potatoes. Call mother. Walk dog. Get haircut.
    – Michael Harvey
    Nov 19 at 12:37
  • 2
    consistent is not a verb but an adjective.
    – TimR
    Nov 19 at 12:51
  • 13
    Commit messages are closer to titles, like titles of newspaper articles or books, than to verbal sentences. You want them to be brief and succinct, to convey a clear message in as few words as possible. The best argument against adding the word "to" in front of every verb is that this word is useless and doesn't convey any meaning.
    – Stef
    Nov 20 at 11:15
  • 1
    This is a great question. How to explain it? These sentence fragments describe what WAS done in the commit, but they are described by the commit (think of the commit as a person) at the time of the commit.
    – Fattie
    Nov 20 at 14:11
  • 1
    Note that "naked" commit messages, like the example "Consistent ordering of overloaded operations" or as an example "vulgar comments" or "algorithm problems" have an implict "Address ..." or 'Attend to ..." in front of them. "Address consistent ordering of overloaded operations" "Address algorithm problems" and so on.
    – Fattie
    Nov 20 at 14:14

5 Answers 5

Reset to default
38

Commit messages for version control systems often use a particular grammar that's a little different from regular English sentences. As @TimR and @MichaelHarvey said, they use the imperative: similar to entries in a to-do list, they can be written as commands. The imperative form of a verb in English is identical to the bare infinitive, as you noticed. But why is this a command, if these are things someone did in the past?

As pointed to by this answer to an old, but closed, StackOverflow question, there's a style guide for commits for people working on the git project, which includes recommendations for how to write their titles:

present-tense

The problem statement that describes the status quo is written in the present tense. Write "The code does X when it is given input Y", instead of "The code used to do Y when given input X". You do not have to say "Currently"---the status quo in the problem statement is about the code without your change, by project convention.

imperative-mood

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. Try to make sure your explanation can be understood without external resources. Instead of giving a URL to a mailing list archive, summarize the relevant points of the discussion.

So the point of view of the titles is "by including this commit, you are instructing your version control software to __________", where _____ is the imperative title. Their "present" is the time immediately before the commit is applied, so the changes are still "to-do".

"Time" is changeable in version control systems. Even if a commit was created yesterday, someone can apply it tomorrow.

Improve this answer
3
  • 7
    @Fattie "They are precisely describing what WAS done in that commit" – Yes and no. Commit messages describe what the author of the commit did to their code in order to produce the commit, and what the commit will do to my code if I decide to merge it. The event is both a past event and a future event.
    – Tanner Swett
    Nov 20 at 16:23
  • I'm afraid that's not correct, TS. A commit, describes, what was done in some code. And that's that. Whether or not that code was merged (to where? what?), is or is not in some particular branch, is or is not in production (in trickle? in widespread use? this is a local tool not used in an app or web site? regressed? legacy'd? not yet set as available on google play? .. or whatever) is all irrelevant.
    – Fattie
    Nov 20 at 17:34
  • @DanGetz awesome, I deleted my suggestion to avoid confusion. Amazing answer, i did not know about that style guide !!!!!!!!!!
    – Fattie
    Nov 20 at 17:35
3

These are "imperatives", items that must be done.

P.S. In other words, a task. A task can begin life in the to-do state and it can later enter the completed state, but the form of the verb used to express the idea of Task, the bare infinitive, doesn't change to reflect task status.

Improve this answer
5
  • 3
    Usually this is true for lists, but I wonder: in this case this is a list of things already done, not a regular to-do list. Each item is a description of what its contents did or do, depending on your point of view. It still might be an imperative, but in that case we need to figure out the point of view, it's not quite "items that must be done".
    – Dan Getz
    Nov 19 at 13:40
  • 2
    Those are the instructions that were given or that context made clear needed to be done: Fix this, merge that, etc etc. It is a to-do list that simply was left "as is" to serve as the record of instructions received/must-do items recognized, rather than edited to say "Fixed this, merged that, ...". That the instructions have been carried out is implicit.
    – TimR
    Nov 19 at 14:07
  • 1
    Lol that's exactly NOT what they are :)
    – Fattie
    Nov 20 at 14:07
  • No, they are the things that will happen if you apply the commit, generally.
    – coppereyecat
    Nov 20 at 22:46
  • @coppereyecat They began as things that needed to be done to the active codebase. Until they are committed, they have not yet been applied to the codebase.
    – TimR
    Nov 20 at 23:08
2

One way to understand commit messages is that they answer the question "What will be the result of merging and deploying this commit?". In addition, we omit the subject (it's implicitly the programmer or computer, depending on the specific type of change) and often elide noise words like articles to keep it brief.

Improve this answer
0

I don't remember where, but I have seen a following justification for this convention:

  • using Add instead of Adds saves 1 character, which matters if you want to keep the title within the limit of 80 chars
  • language-wise, it makes sense if you prepend the commit message with an (implied) prefix "When applied, this commit will..."
Improve this answer
0

In the case of Spring, commit titles seem to be copied directly from the ticket tracking system where the grammar does make sense. If you look at individual commits, they link back to specific tickets as "Closes gh-12345" and the title of the ticket matches exactly the title of the commit. If you want to have the ticket and commit titles match exactly then at least one will have odd grammar.

Improve this answer

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .