Writing commit messages that explain why

Goal

Make the history answer the question a future reader will ask: why was this change made and what did it intend?

Prerequisites

One logical change per commit. If a diff mixes a refactoring with a behaviour change, split it first; a message cannot rescue a mixed commit.

Steps

1. Write a summary line of roughly 50 characters in the imperative mood ("Reject stale If-Match tokens"), as recommended in Pro Git's commit guidelines. It appears in logs, blame views and review tools.
2. Leave a blank line, then explain the motivation: what problem existed, what alternatives were considered, what the change deliberately does not do.
3. Mention observable consequences: new behaviour, migration steps, changed defaults. Reference the issue or discussion by identifier rather than by pasting it.
4. Do not describe the diff line by line; the reviewer can read the diff. Describe what the diff cannot show.
5. Re-read the message after a break. If it only says "fix bug" or "update", it fails the test in the next section.

Expected result

A reader who sees only the message, without the diff, can state the intent and the trade-off. git log --oneline reads as a list of decisions, not a list of files touched.

Limits and test basis

Style rules such as line length are conventions from the cited guide, not requirements of Git itself. Automated commit-message linters can check shape, not meaning; the "why" test still needs a human or a careful agent.