Amey-Thakur Commit messages
A commit message is documentation with a captive audience: everyone who ever
runs git blame on this line. Write for the person debugging at 2 a.m. two
years from now.
Method
- One change per commit. If the diff mixes a bug fix with a rename and a formatting pass, split it before writing anything. A message cannot be honest about three changes at once.
- Subject line: imperative, ≤ 50 characters, no trailing period. "Fix stale cache on user switch", not "Fixed some caching issues". The test: the subject completes the sentence "If applied, this commit will ...".
- Body: the why, not the what. The diff already shows what changed. The body carries what the diff cannot: why this approach, what else was tried, what breaks without it, which trade-off was accepted. Wrap at 72 characters. A one-line body beats a missing one: "Without this, deleting a notebook left its documents in search results."
- Reference, don't recount. Link the issue or incident instead of restating it; state behavior instead of narrating your afternoon.
- Never write these subjects: "fix", "wip", "updates", "address comments", "more changes". Each is a hole in history exactly where someone will need a rope.
Litmus tests
- Could a reviewer decide whether to cherry-pick this commit onto a release branch from the message alone?
- Does the message still make sense with no access to the pull request, the chat thread, or you?
- If this commit causes a regression, does the message give the person reverting it enough context to know what they are giving up?
Boundaries
Follow the repository's existing convention when one exists (Conventional Commits prefixes, issue-tag prefixes, co-author trailers): consistency in a shared history outranks personal taste. This skill governs the content; the project governs the shape.