A commit message is documentation for your future self and every other developer who will ever run git blame on that line — worth the extra thirty seconds it takes to write one properly.
# Bad: says WHAT changed, which the diff already shows "fix bug" "update code" "changes" # Good: says WHY, which the diff can't show "Fix race condition in order processing when two requests arrive within the same millisecond The previous check-then-update pattern wasn't atomic, allowing duplicate orders under concurrent load. Switched to a single atomic UPDATE with a WHERE clause instead."
The Structure That Works
- A short (under ~50 char) summary line, imperative mood (“Fix”, not “Fixed” or “Fixes”)
- A blank line, then a body explaining why the change was needed, not just what it does
- Reference the issue/ticket number if one exists, for traceability
The real test of a good commit message: six months from now, does it explain the reasoning well enough that nobody needs to ping the original author to understand why the code looks the way it does? The diff already shows what changed — the message’s entire job is to capture the why, which is the part that disappears from institutional memory the fastest.