Writing a good commit message

Every commit message is a small note to the future — usually to you, debugging at some unpleasant hour. The diff already shows what changed; the message exists to capture why. Treated as documentation, your history becomes a searchable record of every decision the project ever made.

The structure

A solid message has a short subject line and, when needed, a body:

Fix off-by-one in pagination

The page count used <= instead of <, so the last page was always
empty. Switch to < and add a test for the exact-multiple case.

The conventions that make this work everywhere:

• Subject ≤ ~50 chars, imperative mood ("Fix", "Add", "Remove" — as if completing "this commit will…"), no trailing period.
• Blank line between subject and body (tools rely on it).
• Body wraps at ~72 chars and explains the why and any context the diff can't show.

Why the "why" matters

A year from now, git log and git blame will lead someone to this commit asking "why on earth is it done this way?" The diff shows the change; only the message can explain the reasoning, the constraint, or the bug it fixed. That's the difference between history that answers questions and history that creates them.

Small, focused commits

A good message is easy to write when the commit does one thing. If you can't summarise a commit in one line without "and", it's probably two commits. Focused commits also make git bisect precise — when it points at the culprit, a small, well-described commit tells you immediately what broke.

Where to go next

Commit messages document individual changes. For the big, hard-to-reverse decisions, you want something more durable. Next: Architecture Decision Records.