| name | git-commits |
| description | Best practices for creating high-quality Git commits. Covers commit message conventions (Conventional Commits), atomic commits, staging strategies, and when to amend vs create new commits. Helps AI agents generate clean, meaningful commit history. |
Git Commit Best Practices
Purpose: This skill teaches AI agents to create high-quality commits with clear messages, proper granularity, and effective use of the staging area.
Core Principles
- Atomic Commits - One logical change per commit
- Clear Messages - Follow Conventional Commits format
- Meaningful History - Each commit tells a story
- Smart Staging - Stage only what belongs together
Commit Message Format
Conventional Commits Structure
<type>(<scope>): <subject>
<body>
<footer>
Type Categories
feat:
fix:
docs:
style:
refactor:
perf:
test:
chore:
feat(auth): add password reset functionality
fix(api): handle null response in user endpoint
docs(readme): update installation instructions
refactor(parser): simplify token extraction logic
Subject Line Guidelines
feat(auth): add OAuth2 login support
fix(cart): prevent duplicate items
docs(api): document rate limiting
feat(auth): added some authentication stuff
fix(cart): fixed a bug
docs(api): updated the documentation to include information about rate limiting
Rules:
- Use imperative mood ("add" not "added" or "adds")
- No period at the end
- Keep under 50 characters
- Capitalize first letter after type
- Be specific about what changed
Body Guidelines
feat(cache): add Redis caching layer
Improves API response time by 80% for frequently accessed data.
Uses Redis with 1-hour TTL for user profile and product catalog
endpoints. Falls back to database if Redis is unavailable.
Related to performance optimization initiative.
feat(cache): add Redis caching layer
Added Redis caching.
When to include body:
- Why the change was needed
- How it solves the problem
- Any important implementation decisions
- Side effects or limitations
- Related issues or context
When to skip body:
- Self-explanatory changes (e.g., "fix(typo): correct variable name")
Footer Guidelines
feat(api): change user endpoint response format
BREAKING CHANGE: User API now returns camelCase instead of snake_case.
Migration guide: https://docs.example.com/migration/v2
fix(auth): prevent token expiration race condition
Closes
Refs
feat(search): implement full-text search
Co-authored-by: Jane Doe <jane@example.com>
Atomic Commits
What is an Atomic Commit?
Definition: One commit = one logical change
git commit -m "feat(auth): add login endpoint"
git commit -m "feat(auth): add logout endpoint"
git commit -m "test(auth): add login tests"
git commit -m "feat(auth): add login, logout, password reset, and tests"
Benefits
- Easy to review - Reviewer focuses on one change
- Easy to revert - Undo specific change without affecting others
- Easy to cherry-pick - Apply specific change to another branch
- Clear history - Each commit has clear purpose
How to Create Atomic Commits
git add src/auth.js src/api.js
git commit -m "feat(auth): add token refresh mechanism"
git add tests/auth.test.js
git commit -m "test(auth): add token refresh tests"
git add .
git commit -m "feat(auth): add token refresh and tests"
Decision Tree: Should This Be One Commit?
Does this change have a single, clear purpose?
├─ YES → Can it be described in one sentence?
│ ├─ YES → One commit ✓
│ └─ NO → Multiple commits
│
└─ NO → Multiple commits
Examples:
├─ "Add login validation" → One commit ✓
├─ "Add login and signup" → Two commits
└─ "Add login, fix bug, update docs" → Three commits
Staging Strategies
Strategy 1: Partial File Staging
git add -p src/app.js
git commit -m "feat(app): add error handling"
git add -p src/app.js
git commit -m "refactor(app): extract validation logic"
Strategy 2: Multiple Commits from Unstaged Work
git status
git diff
git add src/feature-a.js src/utils.js
git commit -m "feat(feature-a): implement feature A"
git add src/feature-b.js
git commit -m "feat(feature-b): implement feature B"
git add tests/
git commit -m "test: add tests for features A and B"
Strategy 3: Amend Last Commit
git add forgotten-file.js
git commit --amend --no-edit
git commit --amend -m "feat(auth): add login endpoint and middleware"
git add forgotten-file.js
git commit -m "feat(auth): add missing middleware file"
Common Workflows
Workflow 1: Making a Feature Commit
git status
git diff
git add src/feature.js src/api.js
git diff --staged
git commit -m "feat(feature): add user profile customization
Allows users to customize avatar, bio, and theme preferences.
Settings are persisted to user preferences API endpoint.
Closes #234"
git log -1 --stat
Workflow 2: Making Multiple Atomic Commits
git status
git add src/core.js
git commit -m "feat(core): add data validation layer"
git add src/api.js
git commit -m "feat(api): integrate validation with endpoints"
git add tests/
git commit -m "test(validation): add comprehensive validation tests"
git add docs/
git commit -m "docs(validation): document validation rules"
Workflow 3: Fixing a Bug
git add src/buggy-file.js
git commit -m "fix(cart): prevent duplicate items on double-click
Added debounce to 'Add to Cart' button and server-side duplicate
check. Prevents race condition when users click rapidly.
Fixes #567"
Workflow 4: Amending vs New Commit Decision
Did I already push this commit?
├─ NO → Safe to amend
│ └─> git commit --amend
│
└─ YES → Create new commit instead
└─> git commit -m "fix: ..."
Is this a fixup for recent commit?
└─> Consider git commit --fixup=<sha>
Then use git rebase -i --autosquash before pushing
Workflow 5: Refactoring Commits
git add src/parser.js
git commit -m "refactor(parser): extract token validation to separate function
No behavior change. Makes code more testable and readable."
git add src/parser.js
git commit -m "feat(parser): add support for nested tokens
Now supports tokens in format {{parent.child.value}}"
Common Mistakes to Avoid
Mistake 1: Vague Commit Messages
git commit -m "update"
git commit -m "fix bug"
git commit -m "changes"
git commit -m "wip"
git commit -m "feat(auth): add JWT token expiration check"
git commit -m "fix(api): handle null values in user profile endpoint"
git commit -m "refactor(parser): simplify regex patterns"
git commit -m "docs(readme): add Docker setup instructions"
Mistake 2: Mixing Unrelated Changes
git add .
git commit -m "feat: add login, fix cart bug, update docs"
git add src/auth.js
git commit -m "feat(auth): add OAuth login support"
git add src/cart.js
git commit -m "fix(cart): prevent negative quantities"
git add docs/
git commit -m "docs(api): update authentication endpoints"
Mistake 3: Committing Debug Code
git add src/app.js
git commit -m "feat(app): add feature"
git diff --staged
git add src/app.js
git commit -m "feat(app): add feature"
Mistake 4: Too Large or Too Small Commits
git commit -m "feat(auth): complete authentication system"
git commit -m "add semicolon"
git commit -m "fix typo"
git commit -m "add newline"
git commit -m "feat(auth): add login endpoint"
git commit -m "feat(auth): add logout endpoint"
git commit -m "feat(auth): add token refresh mechanism"
git commit -m "test(auth): add authentication tests"
Mistake 5: Amending Pushed Commits
git push origin feature-branch
git add forgotten.js
git commit --amend --no-edit
git push --force origin feature-branch
git push origin feature-branch
git add forgotten.js
git commit -m "feat(auth): add missing validation helper"
git push origin feature-branch
Commit Message Templates
Template for Features
feat(<scope>): <what you added>
<why this feature is needed>
<how it works (if not obvious)>
<any limitations or considerations>
Closes
Template for Bug Fixes
fix(<scope>): <what you fixed>
<what was wrong>
<how you fixed it>
<why this approach>
Fixes
Template for Refactoring
refactor(<scope>): <what you refactored>
No behavior change. <why refactor was needed>
<what improved (readability, performance, maintainability)>
Integration with AI Code Generation
When AI agents generate code that needs committing:
1. Analyze Changes Before Committing
git status
git diff
2. Create Appropriate Commit Message
git commit -m "feat(api): add rate limiting middleware
Implements token bucket algorithm with 100 requests/minute limit.
Returns 429 status with Retry-After header when limit exceeded.
Addresses security requirement from issue #789"
git commit -m "add rate limiting"
3. Split Large Changes
git add src/rate-limiter.js
git commit -m "feat(api): add rate limiting middleware"
git add tests/rate-limiter.test.js
git commit -m "test(api): add rate limiter tests"
git add docs/api.md
git commit -m "docs(api): document rate limiting"
git add .
git commit -m "add rate limiting with tests and docs"
Quick Reference Checklist
Before every commit, ask:
Advanced: Commit Message Psychology
Good commit messages answer:
- What changed? (Subject line)
- Why was it needed? (Body - business reason)
- How does it work? (Body - technical approach)
- What are the side effects? (Body - impacts)
feat(search): implement fuzzy search algorithm
Users frequently make typos in search queries, resulting in zero
results and poor experience. Implemented Levenshtein distance-based
fuzzy matching with tolerance of 2 characters.
Performance impact: ~50ms additional latency for searches, acceptable
given improved user experience. Results are cached for 5 minutes.
Closes
Summary
Key Principles:
- One commit = one logical change (atomic commits)
- Use Conventional Commits format (type, scope, clear subject)
- Explain why, not just what (meaningful commit messages)
- Stage strategically (use
git add -p for partial staging)
- Never amend pushed commits (creates new commit instead)
Quick Command Reference:
git add <file>
git add -p <file>
git diff --staged
git commit -m "type(scope): msg"
git commit --amend --no-edit
git log -1 --stat
Remember: Commits are documentation of your project's history. Write them for humans who will read them 6 months from now.
