Remember the scene in "Monty Python's Life of Brian" when Roman centurion catches young Brian writing the graffito “Romans go home” on governors palace? While completely overseeing the graffito's content, the centurion is infuriated by Brian’s horrible Latin grammar, so he tyrannizes him to analyze and correct the sentence, word by word. One error was that verb “eunt” should have been in the imperative mood, as "ite". Well, Git also demands commit messages to be in imperative, and many of us developers make exactly the same error as Brian.
Artwork by Hervé Hubert
As soon as changes in developer’s code have reached some meaningful increment, it is time for them to be committed to the repository, otherwise, they get lost, or even worse, they go bad. And as the codebase gets larger, the number of commits quickly grows. Developers need to be able to find and identify them, which is why it's more than important to have meaningful commit messages.
Git documentation gives several guidelines on how to properly format and phrase them. The subject line should have a length of up to 50 characters. Body text should be separated from the subject with a blank line, not only for readability but to avoid confusing tools like rebase. It should be wrapped around 72 characters per line. Git also suggests capitalizing the first letter of the subject, but that varies across projects, because it often begins with ticket number and/or the main category of the commit, such as feature, fix, or refactoring, for the purpose of tracking and external service integration. There is also a commonly accepted convention not to end subject with a dot because it is redundant.
Most developers stick to these rules because it is not difficult to follow them and there are also tools to help and auto-fix them. However, though the rule of using imperative mood is pretty much undisputed, or at least I haven’t found any article arguing against it, many developers tend to neglect it or completely ignore it.
What is imperative mood and what is mood in general?
In linguistics and grammar, mood is the category reflecting speaker’s or writer’s attitude towards the subject. Similarly like tense, mood is a form of verb, from which it transmits sense to the entire sentence or sub-clause. The most common mood is indicative, which is used to express either a statement of fact (declarative) or a question (interrogative). Most of this very text is in indicative mood, and so are most of wrongly phrased Git commit messages.
The second commonly used mood is imperative, which reflects command or request that some action is performed. That is the mood that Git documentation suggests for commit messages, and it is also used by Git itself when auto-generating a message for merge or revert commit.
Properly phrased Git message, in imperative mood, is for example:
Fix vertical alignment
Wrongly phrased messages for the same commit, all in indicative mood, would be:
Fixed vertical alignment (past simple tense)
Fixes vertical alignment (present simple tense)
Fixing vertical alignment (present continuous tense)
Fix for vertical alignment (using the verbal noun instead of the verb)
Vertical alignment fixed (present with using the verb in the passive voice, with form equal to past tense)
If you are a developer, you can probably remember even more models. Some developers use commit message to express their own current emotional "mood", or to write down some random thought. Not to mention creativity such as empty commit line, elaborateness such as "1" and meaningfulness like "uyqtrwuyetr", in some cases even "nbvmxbcmvnbkfbx".
To be honest, I am not sure if I'd be happy to see my lifetime Git log, not to mention my previous SVN log.
But, to get serious, maybe there is an explanation of why many developers don't use imperative as they should.
Why do people hate imperative?
As its name suggests, imperative is used to tell someone what to do. Whether it is a command, request, or merely an appeal, many people don’t like to hear it. In many languages, it is considered impolite to use imperative when you speak to an unknown person, even if it is softened with “please”. You will more likely use a sentence like:
- Could you please close the window?
- Könnten Sie bitte das Fenster schließen?
- Kunt u alstublieft het raam dichtdoen?
- Možete li molim Vas da zatvorite usta?
So, you will use the verb in the interrogative form, combine it with a polite modal verb, usually in the past tense, and you'll still take care to add “please”. The person you address is nevertheless expected to do what you request, but it sounds more respectful. But how would it sound in a commit message?
Another reason why some developers perhaps avoid using imperative is that they don't understand to whom is such a sentence addressed. It is understood that imperative in commit message needs to be in the second person, so, who is that "person"? Do you talk to yourself? Or you talk to your code as if it were human? Or you transcribe the message from your QA tester, product owner, or whoever gave you the task in the first place?
Then why should you use it for commit messages?
Well if your repo can live with all the rubbish in your code, it won’t be offended by your imperative commit messages, and it won't have any ontological thoughts about whom is the message addressed to.
Of course, many developers do adhere to using the imperative mood, for the sake of consistency and to make search and back-tracing easier. Those reasons are valid enough, but in my opinion, there is more to it than that. It's exactly the purpose of this article, not to remind of things already written in many other articles, but to try to answer “why”. Especially because of those developers whose nature resists adopting those rules for which they don’t see a reason clearly enough.
So, to begin with, why is it wrong to say “fixed”, either in active or passive voice? Because commit message should semantically reflect the intent of the commit, not the assumed outcome of it. In other words, the commit might not have necessarily “fixed” what the developer thinks it has. Many times final decision on that is not on developer either, but on QA tester or somebody else.
Same goes for using present simple tense (“fixes”), with the only difference in tense. By stating that some change in code “fixes” something, developer implies the outcome of certain action the same way as above, instead of remaining in scope of intent. In addition, this way of phrasing it is quite ugly.
Why is then “fixing” wrong to use for commit message? Well because gerund form, used to build present continuous tense, is typically used for action that is currently running, that is “in progress”, while commit message is, quite the opposite, supposed to declare a finished action, a meaningful unity of code changes, even with all the awareness that it might not be the last commit with the same purpose.
It is most difficult to explain why not to use a phrase with a verbal noun, such as “fix for vertical alignment”. In this case, it is even equal to the same verb in imperative mood, and I deliberately used it because it is probably the most often used verb in Git, but in many other cases corresponding verbal noun is different, for example, “remove” vs “removal”.
Anyway, in my opinion, the wrong thing about replacing the verb with a verbal noun is that such expression usually doesn’t contain a verb at all. Denoting any action, finite or infinite, is clearer as such with a verb than without it. Speaking of which, the word “commit” in real-life English exists only as a verb. Only in Git vocabulary, it serves as either a verb or noun.
Luka behind his 'desk' at his home office
Sometimes you commit your work because you finished it, or at least some part of it. Sometimes, on the other hand, you do it because you need to switch to another branch, or because you realize there is perhaps already too much code for one commit, which is exactly the case with this article. So, let me "commit it".
You might ask, why is the title in indicative mood. Well, because this is not a commit, but an article.
You might also ask if I blabber about linguistics and grammar so much, why do I say "makes me feel good" if the correct way is "makes me feel well". Well, that is absolutely true, but just imagine if James Browns named his song "I feel well". What could he rhyme it with? Only with "What the hell" or "I bet you can tell".