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 |
The message following the conventions best is Add validation for empty email field.
It is imperative, specific about what changed, and around 40 characters, so it survives a one-line log view intact.
The alternatives each fail a different rule. updated the files says nothing a reader could act on, since every commit updates files. Added validation is past tense where Git convention is imperative, which matters mainly for consistency with Git's own generated messages like Merge branch and Revert. And a run-on list of every change in one message is usually a signal about the commit rather than the wording: work that needs a list to describe it probably wanted to be several smaller commits.
When one line is not enough
Bigger changes get 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, so it has to stand alone. The body carries the why, which is the one thing a diff can never show: the diff proves the division is now guarded, and only the body explains that an empty cart was the case nobody had considered.
Both parts can be written from the terminal by repeating the flag, as in git commit -m "subject" -m "body", where Git inserts the blank line between them. Most engineers let git commit open an editor instead, since writing a paragraph inside shell quotes is awkward and easy to get wrong.
Git separates the subject from the body with a blank line. Everything before it is the subject, everything after is the body.
The convention is subject, blank line, body, and tools depend on it. git log --oneline prints the subject only, and hosting sites use it as the title of a commit page.
Skipping the blank line has a visible cost. Git then treats the entire message as one run-on subject, so a paragraph of explanation ends up crammed into a one-line log view and any length limit a tool applies will truncate it mid-sentence.
Phrasing a message as a command puts it in the imperative mood.
It is the mood used for instructions, as in stop, look, add. That is why Add search bar is conventional and Added search bar is not.
The reason behind the convention is consistency with Git itself. Git's own automatically generated messages are imperative, including Merge branch 'feature' and Revert "Add search bar", so imperative messages of your own read as part of the same list rather than clashing with it. A useful test is to read the subject after the phrase "this commit will", which makes Add search bar fit and Added search bar obviously wrong.