wxy _git-commit
Overview
Standardizes git commit process using Conventional Commits format. Replaces inline commit messages with structured .github/COMMIT_DESCRIPTION.local.md file for clarity and consistency.
When to use: Every code change, feature, fix, or documentation update
Key principle: Never use git commit -m "..." for complex commits - use structured file format instead
Conventional Commits Format
Basic Structure
<type>(<scope>): <subject>
<body>
<footer>
Where:
- type:
feat,fix,docs,style,refactor,test,chore,perf,ci - scope (optional): Affected component (e.g.,
auth,ui,core) - subject: Short description (≤50 chars, imperative mood, no period)
- body: Detailed explanation (≤72 chars per line)
- footer: References (e.g.,
Fixes #123) or breaking changes
Commit Types
| Type | Purpose | Example |
|---|---|---|
feat |
New feature | feat(auth): add OAuth integration |
fix |
Bug fix | fix(ui): correct button alignment |
docs |
Documentation | docs: update API reference |
style |
Code style | style: format TypeScript files |
refactor |
Code restructure | refactor: simplify state management |
test |
Testing | test: add auth integration test |
chore |
Maintenance | chore: upgrade dependencies |
perf |
Performance | perf: optimize database queries |
ci |
CI/CD changes | ci: add test coverage workflow |
Workflow (5 Steps)
Step 1: Stage Specific Files
Always explicitly stage files (never use git add .):
# Stage specific files only
git add src/file1.ts src/file2.ts
# Or review changes before staging
git diff --name-only
git add <files>
Step 2: Create Commit Description File
Copy template, fill in details, maintain required signature:
# Copy template and edit
cat .agent/skills/_git-commit/references/commit_template.md > .github/COMMIT_DESCRIPTION.local.md
# Then edit with actual changes
Template structure (keep all sections):
feat(scope): Brief description
## Changes
- Change 1
- Change 2
## Technical Details
- Implementation notes
## Testing
- What was tested
---
🤖 Generated by _git-commit skill
Step 3: Verify Format
Check before committing:
# Verify signature exists
grep -i "git-commit\|🤖" .github/COMMIT_DESCRIPTION.local.md
# Verify type format on first line
head -1 .github/COMMIT_DESCRIPTION.local.md | grep -E "^(feat|fix|docs|style|refactor|test|chore|perf|ci)"
Step 4: Execute Commit
git commit -F .github/COMMIT_DESCRIPTION.local.md
Step 5: Clean Up
rm .github/COMMIT_DESCRIPTION.local.md
Complete workflow in one command:
git add src/file.ts && \
git commit -F .github/COMMIT_DESCRIPTION.local.md && \
rm .github/COMMIT_DESCRIPTION.local.md
Examples
Example 1: Simple Fix
fix(storage): correct database transaction timeout
Transactions failed when processing >1000 records.
Split into batches of 100 using segment transactions.
Fixes #456
Example 2: Feature
feat(core): implement caching layer
Reduces database load by caching query results.
## Changes
- Add CacheManager class
- Configure TTL (default 5 min, configurable)
- Add unit tests
## Performance
- 40% reduction in database queries
- Query latency improved from 200ms to 50ms
Fixes #123
Example 3: Refactor
refactor(api): unify provider interfaces
Consolidates multiple provider implementations into single factory pattern.
## Breaking Changes
BREAKING CHANGE: Removed legacy Provider class, use ProviderFactory instead
## Migration
1. Update imports to use ProviderFactory.create()
2. Review error handling (new ProviderError type)
Fixes #789
Critical Guidelines
❌ Prohibited:
git commit -m "inline message"(use file instead)git add .(explicitly list files)- Omitting signature line
- Mixing types (feat+fix in one commit)
✅ Required:
- Explicit file list with
git add - Signature line:
🤖 Generated by _git-commit skill - Type conformance: feat/fix/docs/etc
- First line ≤50 characters
Common Mistakes
Missing signature:
- Add to description file:
🤖 Generated by _git-commit skill
Accidentally in master:
# Create feature branch
git checkout -b feature/name
git cherry-pick <commit> # Move commits if needed
Wrong type:
- Review type table above
- Amend:
git commit --amend
Forgot to clean up .local.md:
- File won't be committed (ignored by .gitignore)
- Delete manually to avoid confusion
Quick Checklist
Before committing:
- Files explicitly staged (not
git add .) - Type matches list (feat/fix/docs/etc)
- Subject ≤50 characters
- Body ≤72 chars per line
- Signature line present
- Issue reference included (if applicable)
- File correctly saved as
.github/COMMIT_DESCRIPTION.local.md
Related Skills
- _release-process: Release versioning (uses _git-commit for release commits)
- _pr-creator: PR with commit reference
- _code-health-check: Code quality before commit