git-commit-writer

# Git Commit Writer ## Overview This skill enables writing professional Git commit messages that follow industry best practices based on Chris Beams' widely-adopted guidelines. Well-crafted commit messages preserve institutional knowledge, improve code maintainability, and make collaboration more effective in either Codex or Claude Code. ## When to Use This Skill Activate this skill when: - Writing a new commit message for code changes - Reviewing or improving an existing commit message - User asks "how should I write this commit message?" - User provides a poor commit message and needs help improving it - User mentions git commit, version control, or commit standards - User is about to commit code and needs guidance ## The Seven Core Rules Apply these rules to every commit message: ### 1. Separate subject from body with a blank line Place one blank line between the subject line and the body text. Git tools rely on this separation. ```text Fix authentication bug in user login The bcrypt comparison was using the wrong salt parameter. This commit corrects the parameter and adds unit tests. ``` ### 2. Limit the subject line to 50 characters Keep subjects concise and scannable. GitHub warns beyond 50 characters and truncates at 72. ✅ Good: `Add user authentication with JWT tokens` ❌ Too long: `Add comprehensive user authentication system with JWT tokens and refresh` ### 3. Capitalize the subject line Start with a capital letter for consistency. ✅ Good: `Refactor authentication module` ❌ Bad: `refactor authentication module` ### 4. Do not end the subject line with a period Periods waste space in the 50-character limit. ✅ Good: `Fix memory leak in sync process` ❌ Bad: `Fix memory leak in sync process.` ### 5. Use the imperative mood in the subject line Write commands, not descriptions of what was done. **The golden test:** Complete this sentence: "If applied, this commit will **[your subject line]**" ✅ Imperative: `Fix bug in user login` ✅ Test: "If applied, this commit will **fix bug in user login**" ❌ Past tense: `Fixed bug in user login` ❌ Test: "If applied, this commit will **fixed bug in user login**" (grammatically incorrect) **Common imperative forms:** - Fix, Add, Remove, Update, Refactor, Improve - Merge, Revert, Document, Extract, Consolidate **Avoid:** - Fixed, Added, Removed (past tense) - Fixes, Adds, Removes (present tense) - Fixing, Adding, Removing (present participle) - I fixed, I added (first person) ### 6. Wrap the body at 72 characters Hard-wrap body text at 72 characters for proper display in terminals and Git tools. ### 7. Use the body to explain what and why vs. how The code shows **how** something was done. The commit message explains: - **What** was changed - **Why** it was changed - What problem was being solved - Why this solution was chosen ## Workflow for Writing Commit Messages ### Step 1: Understand the Changes Before writing the commit message, review what was changed: - What files were modified? - What functionality was added, removed, or fixed? - Is this a single logical change (atomic commit)? ### Step 2: Craft the Subject Line Write a subject line that: 1. Completes: "If applied, this commit will **[subject]**" 2. Uses imperative mood (Fix, Add, Remove, Update, etc.) 3. Stays under 50 characters 4. Starts with a capital letter 5. Has no ending period **Subject line patterns:** | Pattern | Example | |---------|---------| | Fix [issue] in [area] | `Fix race condition in cache invalidation` | | Add [feature] to [area] | `Add dark mode support to user interface` | | Remove [thing] from [area] | `Remove deprecated authentication methods` | | Update [thing] to [state] | `Update dependencies to latest versions` | | Refactor [area] for [reason] | `Refactor auth logic for maintainability` | | Improve [aspect] of [area] | `Improve error messages in validation` | ### Step 3: Decide If a Body Is Needed **Body is required when:** - The change is not self-explanatory from the subject and diff - There's important context or reasoning to preserve - The change fixes a bug with non-obvious root cause - Trade-offs or alternatives were considered - The change has side effects or consequences **Body is optional for:** - Simple, obvious changes - Typo fixes (though consider if body would help) - Very small refactorings with clear purpose ### Step 4: Write the Body (If Needed) Structure the body to answer: 1. **What was the problem or motivation?** - What bug occurred or what was missing? - What user need is being addressed? 2. **Why this solution?** - Why was this approach chosen? - What alternatives were considered? 3. **What are the effects?** - Are there side effects or consequences? - Does this enable future changes? 4. **References** - Link to related issues: `Fixes #123` - Link to PRs: `Related to PR #456` - Link to documentation or discussions **Example template:** ```text [Subject line] [What was the problem - 1-2 sentences] [Why this solution - 1-3 sentences explaining the approach] [Optional: Effects, consequences, or next steps] Fixes #123 ``` ### Step 5: Apply Final Checks Before committing, verify: - [ ] Subject line is 50 characters or less - [ ] Subject uses imperative mood - [ ] Subject is capitalized with no ending period - [ ] Blank line separates subject from body - [ ] Body is wrapped at 72 characters - [ ] Body explains what and why, not how - [ ] Related issues are referenced ## Common Scenarios and Examples ### Scenario 1: Simple Bug Fix **User request:** "I fixed a login bug, what should my commit say?" **Response pattern:** ```text Subject: Fix authentication bug in user login Body (optional): The password validation was failing due to incorrect bcrypt salt parameter. This commit corrects the parameter and adds unit tests to prevent regression. Fixes #789 ``` ### Scenario 2: Feature Addition **User request:** "I just added dark mode support" **Response pattern:** ```text Subject: Add dark mode support to user interface Body: Implements a dark color theme toggleable in user preferences. The theme persists across sessions and follows WCAG 2.1 Level AA contrast requirements for accessibility. Uses CSS custom properties for instant theme switching without page reload. Closes #567 ``` ### Scenario 3: Refactoring **User request:** "I cleaned up the authentication code" **Response pattern:** ```text Subject: Extract authentication logic into separate service Body: Authentication code was scattered across multiple controllers, making it difficult to maintain and test. This commit consolidates all authentication logic into a dedicated AuthService. Benefits: - Single responsibility principle compliance - Easier unit testing with dependency injection - Consistent authentication behavior across endpoints No functional changes to authentication behavior. ``` ### Scenario 4: Reviewing a Poor Commit **User provides:** `"Fixed stuff"` **Response pattern:** Suggest improvement: ```text The commit message "Fixed stuff" is too vague. Consider a more descriptive subject like: Fix memory leak in background sync process And add body text explaining: - What was the memory leak? - What was causing it? - How does this fix address it? ``` ## Handling Edge Cases ### Multiple Related Changes If multiple related changes are in one commit: - List them in the body with bullet points - Ensure they're logically related (otherwise split commits) ```text Update authentication system for security - Add rate limiting to login endpoint - Implement JWT token refresh mechanism - Update bcrypt rounds to current best practice These changes work together to improve authentication security after the security audit recommendations. ``` ### Merge Commits Git creates these automatically, typically don't need custom messages. If customizing: ```text Merge branch 'feature/dark-mode' into main Brings dark mode support with accessibility compliance. All tests passing and code reviewed. ``` ### Reverting Commits Use `git revert` which auto-generates messages, but enhance with context: ```text Revert "Add experimental caching layer" This reverts commit abc123def456. The caching layer caused data inconsistencies in production under high concurrent load. Reverting while we investigate the race condition issue. Related to incident #2345 ``` ## Resources This skill includes: ### references/detailed-guide.md Comprehensive guide with: - Detailed explanations of all seven rules - Extensive examples and anti-patterns - Common scenarios and edge cases - Links to authoritative sources Load this reference when: - User asks for detailed explanations - User needs examples of specific patterns - Helping with complex commit scenarios - User wants to understand the "why" behind rules ## Project-Specific Considerations When working in specific projects: - Check for existing commit message conventions in CONTRIBUTING.md or similar files - Follow established patterns in the project's git history - Note any project-specific prefixes (e.g., `feat:`, `fix:`, `docs:`) - Respect team decisions that differ from these guidelines (consistency matters more than personal preference) ## Anti-Patterns to Avoid Never accept these commit message patterns: - ❌ Vague: `Fix stuff`, `Update code`, `Changes`, `WIP` - ❌ Non-imperative: `Fixed bug`, `Updating code`, `I added feature` - ❌ Too long subjects: Anything over 72 characters - ❌ Implementation details in subject: `Change function X to use Y instead of Z` - ❌ Missing context: `Fix bug` (which bug? what was broken?) - ❌ Casual language: `Finally got this working!`, `asdfasdf` ## Success Criteria A well-written commit message should: 1. Allow future developers to understand the change without reading the code 2. Explain the reasoning and context behind decisions 3. Enable quick scanning of git history 4. Preserve institutional knowledge 5. Make code reviews and debugging easier