Writing Commit Messages

Writing Commit Messages

Overview

A commit message is the only place future-you (or future-them) finds out WHY a change happened. The diff shows what; the message has to explain why. The honest agent default is a one-liner subject and no body — fine for trivial changes, lossy for everything else.

Core principle: The message answers "why," not "what." The diff already shows what.

The Format

Subject Line

• Imperative mood: Fix login failure for apostrophe usernames — not Fixed, not Fixes, not Fixing.
• Under 72 chars (50 ideal). If you need more, the body should be doing that work.
• No trailing period.
• Capitalize the first letter.

When To Write a Body

Write a body when ANY of these are true:

• The change fixes a bug — the body explains the root cause and the failure mode
• The change is non-obvious from the diff alone
• The change has a non-obvious motivation (compliance, perf regression, deprecation)
• The change is part of a larger initiative — link to the spec or parent ticket
• The change has subtle behavior (silent failure, edge case, race-condition fix)

Skip the body for: pure renames, formatting / lint fixes, dep version bumps with no behavior change, typo fixes in non-code files.

Body Content

Include:

• Symptom / motivation — what was wrong, or why this exists
• Root cause — why the bug existed (for fixes)
• Approach — only if non-obvious (We chose X over Y because Z)
• Caveats / follow-ups — known limitations, deferred work

Leave out: play-by-play of the diff, redundant restatement of the subject, marketing speak.

Before / After

❌ One-liner reflex (loses the why):

Fix login bug

❌ What-not-why (diff already shows this):

Update src/auth/validator.ts

Removed the .replace() call in validator.ts.

✅ Subject + body that explains the why:

Fix silent login failure for usernames with apostrophes

The validator was stripping apostrophes via .replace(/'/g, '') before
the database lookup, so users like "O'Brien" were queried as "OBrien"
and silently never matched. Removing the replacement passes the
username through unchanged.

Fixes #482

Common Mistakes

| Mistake | Fix | |---|---| | Past-tense subject (Fixed apostrophe bug) | Imperative: Fix apostrophe bug | | Subject longer than 72 chars | Move detail to the body | | Body that restates the subject | Cut it; explain why instead | | Body that walks through the diff | Cut it; reader can read the diff | | No body on a non-trivial bug fix | Add one — what was broken, why, how this fixes it | | Misc improvements / Various fixes | One logical change per commit. Split first. | | Mentioning a ticket number without context | Either explain in the body or just leave the trailer |

Red Flags — STOP

• Subject starts with a past-tense verb
• Subject is your only content for a non-trivial fix
• Body is a list of what you changed (= what the diff shows)
• Multiple unrelated changes in one commit — split first
• About to commit a bug fix with no body explaining the root cause

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gg-mo
• Source: gg-mo/repo-hygiene
• License: MIT
• Homepage: https://github.com/gg-mo/repo-hygiene

Install and usage instructions live in the source repository linked above.