git-commit
Commit with clear messages explaining WHY, following repository conventions
When & Why to Use This Skill
This Claude skill streamlines the version control process by enforcing high-quality Git commit standards. It ensures every commit follows repository conventions, provides a clear explanation of the 'why' behind changes, and includes mandatory safety checks to prevent the accidental submission of secrets or debug code, ultimately enhancing long-term code maintainability and team collaboration.
Use Cases
- Standardizing Team Conventions: Automatically generate commit messages that follow the Conventional Commits specification (feat, fix, refactor) to maintain a clean and searchable project history.
- Improving Code Documentation: Ensure that every change is accompanied by a detailed explanation of the rationale and problem solved, rather than just describing the code diff.
- Security and Quality Assurance: Prevent the accidental commitment of sensitive data like API keys, .env files, or temporary debug logs through a mandatory pre-commit diff review process.
- Atomic Commit Management: Help developers group related changes into single logical units while identifying and separating unrelated modifications for cleaner pull requests.
| name | git-commit |
|---|---|
| description | Commit with clear messages explaining WHY, following repository conventions |
Git Commit
Iron Law
- NO COMMITS WITHOUT REVIEWING GIT DIFF FIRST
- NO COMMIT MESSAGES WITHOUT EXPLAINING WHY
- ONLY COMMIT WHEN USER EXPLICITLY REQUESTS
Process
1. Gather Context (parallel)
git status # Staged/unstaged files
git diff # Unstaged changes
git diff --staged # Staged changes
git log --oneline -5 # Recent commit style
2. Review Changes
- Understand every change in diff
- No secrets (.env, credentials, keys)
- No debug code, console.logs
- Related changes only (one logical unit)
3. Stage and Commit
git add path/to/file1 path/to/file2
git commit -m "$(cat <<'EOF'
feat: add user authentication middleware
Previous implementation left API endpoints unprotected. Adds JWT
validation middleware ensuring only authenticated requests reach
protected endpoints.
EOF
)"
4. Verify
git status # Working tree state
git log -1 --stat # Confirm commit
Message Format
<type>: <subject - imperative mood, 50 chars>
<body - explain WHY, wrap at 72 chars>
Types: feat: fix: refactor: docs: test: chore:
Subject: Imperative mood ("Add" not "Added"), no period, ≤50 chars
Body: Explain WHY, what problem it solves, non-obvious decisions
Pre-commit Hook Changes
If hooks modify files:
- Check authorship:
git log -1 --format='%an %ae' - Check not pushed:
git statusshows "ahead" - If both true:
git add <files> && git commit --amend --no-edit - Otherwise: Create NEW commit
Safety Rules
Never without explicit request:
--force,--force-with-lease--amendon others' commits or pushed commits--no-verify,--no-gpg-signgit reset --hardgit configchanges
Never commit:
.env, credentials, secrets, keys- Broken code (tests must pass)
- Unrelated changes mixed together
Examples
fix: prevent race condition in session creation
Sessions were created before user validation completed, allowing
invalid users to briefly access protected resources. Moves session
creation to after validation succeeds.
refactor: extract validation using Replace Conditional with Polymorphism
Payment processor had 4-level nested conditionals. Applied Fowler's
pattern to create PaymentMethod interface. New payment types now
require zero changes to processor.
Key Takeaways
- Review diff before committing - Never commit unread code
- Explain WHY, not WHAT - Diff shows what; message explains why
- One logical change per commit - Multiple files OK if related
- Only commit when requested - Don't be proactive
- Use heredoc for messages - Ensures proper formatting