Using Imperative Mood in Commit Messages

Imperative Mood in Commit Messages

The Conventional Commits specification and Git's own guidelines recommend writing commit descriptions in the imperative mood. This means writing as if you are giving a command or instruction, rather than describing what you did.

What Is Imperative Mood?

Imperative mood is the verb form used to give orders or instructions:

Mood	Example
Imperative (correct)	"add feature", "fix bug", "update docs"
Past tense (incorrect)	"added feature", "fixed bug", "updated docs"
Present participle (incorrect)	"adding feature", "fixing bug", "updating docs"

Why Imperative Mood?

1. Git itself uses it: Git's auto-generated messages use imperative mood:

   • Merge branch 'feature'
   • Revert "add user validation"
   • Cherry-pick "fix login bug"

2. It completes a sentence: "If applied, this commit will add user authentication"

3. It is concise: Imperative verbs are shorter than past tense or present participle forms

4. It is consistent: Everyone on the team writes in the same voice

Common Conversions

Wrong	Correct
added OAuth support	add OAuth support
fixed memory leak	fix memory leak
removing deprecated API	remove deprecated API
updated dependencies	update dependencies
changes error handling	change error handling
improved performance	improve performance

The Sentence Test

Every commit description should read naturally when completing:

"If applied, this commit will ___."

• "If applied, this commit will add rate limiting to API" ✔
• "If applied, this commit will added rate limiting to API" ✘

Enforcing with commitlint

The @commitlint/config-conventional preset does not enforce imperative mood by default, but you can add a custom rule or use the subject-case rule to enforce lowercase (which naturally encourages imperative mood):

module.exports = {
  rules: {
    'subject-case': [2, 'always', 'lower-case'],
  },
};