Messages are for future readers
Six months from now, someone (probably you) will scan git log --oneline from lesson 3-1 trying to find where a bug appeared. The messages are all they have. Three rules make messages useful:
- Imperative mood: write commands, not reports. "Add login form", not "Added login form" or "adding stuff". Read it as "this commit will... Add login form."
- Say what and why, not how. The diff already shows how.
- Keep the first line around 50 characters, so it fits in one-line views.
| Weak | Strong |
|---|---|
fixed stuff | Fix crash when cart is empty |
changes | Add password reset email |
asdfgh | Remove unused payment code |
Quiz
Which commit message follows the conventions best?
When one line isn't enough
For bigger changes, messages have a subject and a body, separated by a blank line:
Fix checkout crash for empty carts The total calculator divided by the item count, which is zero for an empty cart. Guard the division and show the empty-cart page instead.
The subject is what git log --oneline displays. The body explains why, the context a diff can never show. You can write both from the terminal by repeating the flag: git commit -m "subject" -m "body", though most engineers let git commit open an editor for multi-line messages.
Quiz
In a multi-line commit message, how does Git know where the subject ends and the body begins?
Problem
Commit convention says to write "Add search bar", not "Added search bar". What is the grammatical mood called where you phrase the message as a command?