Write Tim Pope-style Git commit messages. Honors repo-specific commit templates when present. Forbids AI attribution. Use when committing staged changes, amending commit messages, or when someone mentions commit message, git commit, or commit format.
Instrucciones de origen · Vista previa de solo lectura
Más de este repositorio
name
writing-git-commits
description
Write Tim Pope-style Git commit messages. Honors repo-specific commit templates when present. Forbids AI attribution. Use when committing staged changes, amending commit messages, or when someone mentions commit message, git commit, or commit format.
Write clear, professional Git commit messages following Tim Pope's style guide.
Quick Start
This skill activates when committing staged changes, amending a commit message, or when the user mentions "commit message", "git commit", or "commit format". On activation:
NEVER reference Claude, Anthropic, AI, or any AI attribution in commit messages.
No "Co-Authored-By: Claude" lines
No "Generated by AI" notes
No "Claude suggested" comments
No AI tools mentioned anywhere
This is non-negotiable. Violating this rule fails the entire commit.
Bodies Are Prose for Humans
The commit body is user-facing prose: BLUF, active voice, no banned words, no hedging, concrete over abstract. The quick rules and banned-word list are inlined below — most commit bodies are 1-3 paragraphs, so applying them inline is faster than delegating.
The subject line is mechanical (imperative mood, ~50 chars, completion test) and its rules override prose rules where they conflict.
Use bullets for genuinely parallel items; use prose for narrative explanation. Don't bullet-list a single thought.
For long-form prose guidance beyond what's inlined here, see writing-for-humans as further reading.
What Belongs in the Body
The diff already shows WHAT and HOW. The body's monopoly is on WHY. Everything you write must clear two tests.
Test 1: The Diff-Redundancy Test
"Could a future engineer derive this from git log --stat -p alone?"
If yes, delete it. If the entire body fails the test, rewrite it to capture WHY. Only drop to subject-only if the change is truly trivial.
The body exists to capture what the diff CANNOT show:
WHY this change was made (motivation, constraint, external trigger)
Alternatives considered and rejected, and why
Invariants or constraints not visible in the code
Subtle behavior changes a casual reader might miss
Historical or external context (e.g., "Stripe changed their API on 2025-04-01")
A body that paraphrases the diff ("Modified X to add Y, updated Z") adds zero information. Cut it.
Test 2: The Cross-Reference Test
Every reference to another commit, PR, or ticket must either (a) trigger automation, or (b) carry context the reader needs and cannot get from the diff or from this body. Otherwise it is noise.
If $template resolves to a file, read it and follow its conventions. Otherwise, use Tim Pope format.
Tim Pope Format
The Seven Rules
Subject ~50 chars (hard max: 72)
Capitalize the subject line
No period at end of subject
Imperative mood in subject ("Add" not "Added" or "Adds")
Blank line separating subject from body
Wrap body at 72 chars
Body explains what/why, not how
The Completion Test
Every subject line must pass this test:
"If applied, this commit will [your subject line]"
Examples:
"If applied, this commit will Add user authentication" ✓
"If applied, this commit will Fixed the bug" ✗
"If applied, this commit will Refactor payment module for clarity" ✓
Subject Line Verbs
Most action verbs are self-evident (Add, Remove, Update). These are the ones that need disambiguation:
Verb
Use For
Fix
Bug fixes only — not "improvements" or refactors
Refactor
Code restructuring with no behavior change. If behavior changes, use Update
Extract
Breaking code out into a new function/module (no behavior change). Distinct from Move
Move
Relocating existing code without restructuring it
Rename
Renaming files, variables, or functions (no other change)
Replace
Swapping one implementation for another. Distinct from Update (which modifies in place)
Revert
Undoing a prior commit. Include the SHA and WHY in the body
When to Include a Body
Trivial changes (subject only): typo fixes, version bumps, dependency upgrades with no API change, formatting-only commits. If the change is obvious from the diff and would surprise no one, the subject is enough.
Non-trivial changes (write a body): anything that involved a decision. Code review of your future self should be able to ask "why did you do it this way?" and get an answer from the commit message, not from the diff.
The body's job is WHY, not WHAT — the Diff-Redundancy Test still applies. If your draft body paraphrases the diff, rewrite it to explain motivation, rejected alternatives, or constraints. Don't delete it; fix it.
When in doubt, write the body. A paragraph the next reader skips costs them three seconds. A missing paragraph during a bisection costs them an hour.
If the subject feels cryptic at 50 chars: that's a signal the change needs a body, not a sharper subject. Keep the subject as the headline; let the body carry the context the 50-char limit pushed out.
Do not use the body to complete the subject grammatically — the body is WHY, not WHAT. If your subject and first body sentence read as one continuous thought, rewrite both.
Workflow
One commit, one logical change. If the staged diff covers multiple unrelated changes, split it (git add -p, git reset) before drafting a message — vague subjects almost always come from tangled diffs, not bad wording.
Step 1: Gather Context
Decompose the staged changes:
What files changed?
What was the purpose of each change?
What's the unifying theme?
Step 2: Draft Subject Line
Identify the primary action (verb)
Identify the primary object (what was affected)
Combine into imperative statement
Check length (~50 chars)
Apply the completion test
Step 3: Draft Body (if needed)
First, decide if the change is trivial. Trivial → subject only. Non-trivial → write a body, then apply the Diff-Redundancy Test to make sure it captures WHY, not WHAT. If a draft body only restates the diff, rewrite it; don't delete it.
For non-trivial changes:
Lead with the what/why in the first sentence (BLUF) — no "This commit..." preamble
Use active voice — name the actor: "JWTs let any server validate requests" not "requests can be validated"
Cut banned words (see list below) and hedging ("might", "could potentially", "it seems")
Prefer concrete details — numbers, file names, function names — over abstract claims
Format commit message using HEREDOC for proper formatting:
git commit -m "$(cat <<'EOF'
Subject line here
Body paragraph explaining what changed and why.
Wrap at 72 characters per line.
EOF
)"
Examples
Good: Simple Change
Add null check in user validation
Good: With Body
Refactor authentication to use JWT tokens
Swap session-based auth for stateless JWT tokens so any server
can validate requests independently. Sessions forced sticky load
balancing, which blocked horizontal scaling across our three
production regions.
Breaking change: existing sessions invalidate on deploy.
Bad: Restates the Diff
Add email field to User model
Modified UserService.ts to add a new field called `email` to the
User interface. Updated the createUser method to accept the new
field. Added validation in EmailValidator.ts. Updated the tests
in user.test.ts.
Every line is visible in git show --stat -p. The body adds nothing. Rewrite it to explain WHY.
Better:
Add email field to User model
Required for the upcoming password-reset flow. Validate
synchronously on create to fail fast — schema-level constraints
will follow in a separate commit so the migration can be
reviewed independently.
Good: Bug Fix
Fix race condition in order processing
Multiple concurrent orders could decrement inventory below zero
because the check-then-update wasn't atomic. Use database-level
locking to ensure inventory never goes negative.
Fixes #1234
Bad Examples
fixed bug # Not capitalized, not specific
Updated the code. # Period, vague
Add feature for handling users. # Period
adds new authentication system # Not capitalized, not imperative
WIP # Not descriptive
Misc fixes # Too vague
Co-Authored-By: Claude <...> # AI ATTRIBUTION - NEVER DO THIS
Issue References
Place issue references at the end of the body. Use operational forms (Fixes, Closes, Resolves) that trigger automation. Skip decorative references — see Test 2.
Fix memory leak in image processing
The resize operation wasn't releasing the source image buffer
after completion, causing memory to grow unbounded.
Fixes #456
Closes #457
Breaking Changes
Call out breaking changes prominently:
Remove deprecated v1 API endpoints
BREAKING CHANGE: The /api/v1/* endpoints are removed. Clients must
migrate to /api/v2/* which has been available since release 2.0.
Migration guide: docs/migration-v1-to-v2.md
Multiple Related Changes
If a commit touches multiple things, the subject should capture the theme:
Improve error handling across payment flow
- Add retry logic for transient gateway failures
- Log detailed error context for debugging
- Return user-friendly error messages
- Add circuit breaker for repeated failures
Success Checklist
Before finalizing any commit message, verify:
Subject (mechanics):
Passes: "If applied, this commit will [subject]"
Imperative mood (Add/Fix/Update, not Added/Fixed/Updated)
Starts with capital letter
No trailing period
~50 characters (hard max 72)
Body (prose):
Blank line between subject and body
Lines wrap at 72 characters
Explains what/why, not how
No diff-redundant content (passes "could the reader get this from git show?")
