git-commit-messages
Guide for writing descriptive yet succinct git commit messages following best practices. Use this when creating commit messages, reviewing commits, or establishing commit message conventions.
SKILL.mdskills/git-commit-messages/SKILL.md
GitHubGit Commit Messages
This skill helps you write clear, descriptive, and succinct git commit messages that follow industry best practices and make project history more maintainable.
When to Use This Skill
Use this skill when:
- Writing commit messages for code changes
- Reviewing pull requests and commit quality
- Establishing commit message conventions for teams
- Understanding how to structure commit history
- Training team members on commit message best practices
Prerequisites
- Basic understanding of git commands
- Familiarity with your project's commit history
- Knowledge of the changes being committed
Commit Message Guidelines
Basic Structure
A good commit message follows this format:
<type>(<scope>): <subject>
<body>
<footer>
Types
Use these conventional commit types:
- feat: New feature or functionality
- fix: Bug fix
- docs: Documentation changes
- style: Code style/formatting changes (no logic changes)
- refactor: Code refactoring (no feature changes or bug fixes)
- test: Adding or updating tests
- chore: Maintenance tasks, build changes, dependency updates
- perf: Performance improvements
- ci: CI/CD pipeline changes
- build: Build system or dependency changes
Subject Line Rules
- Limit to 50 characters - Keep it concise but descriptive
- Do not end with a period - No punctuation at the end
- Use imperative mood - "Add feature" not "Added feature" or "Adding feature"
- Be specific - Clearly describe what changed
Body Guidelines
- Separate from subject with blank line - Always add a blank line
- Wrap at 72 characters - Maintain readability
- Explain what and why - Describe the change and reasoning
- Use bullet points - For multiple related changes
- Reference issues - Link to tickets or issues when applicable
Footer Guidelines
- Breaking changes - Use "BREAKING CHANGE:" followed by description
- Issue references - Closes #123, Fixes #456, etc.
- Co-authors -
Co-authored-by: Name <email>
Instructions
Step 1: Analyze Your Changes
Before writing the commit message, understand what changed:
- Review the diff - Use
git diff --cachedto see staged changes - Categorize the change - Determine the appropriate type (feat, fix, etc.)
- Identify the scope - Which component, module, or feature was affected
- Note breaking changes - Any changes that break existing APIs
Step 2: Write the Subject Line
Craft a clear, concise subject line:
# Good examples
feat(auth): add password reset functionality
fix(api): resolve null pointer in user validation
docs(readme): update installation instructions
refactor(utils): simplify date formatting logic
# Bad examples (too vague, too long, wrong tense)
"fixed bug" # Too vague
"fixed the bug that was causing the login to fail when users entered invalid credentials" # Too long
"Fixes login bug" # Wrong tense
Step 3: Add Body (When Needed)
Include a body for complex changes:
# Complex feature addition
feat(user-profile): add avatar upload functionality
- Implement file upload validation for images only
- Add image resizing and optimization
- Store avatars in cloud storage with CDN
- Update user profile API to include avatar URLs
Closes #123
Step 4: Include Footer (When Applicable)
Add footer information for special cases:
# Breaking change
refactor(api): change authentication endpoint
BREAKING CHANGE: The /auth/login endpoint now requires
JSON payload instead of form data. Update client code
accordingly.
# Issue reference
fix(database): resolve connection timeout issues
Fixes intermittent database connection failures in
production environment. Added connection pooling and
retry logic.
Closes #456
Step 5: Commit the Changes
Use git to create the commit:
# Stage changes if not already staged
git add .
# Commit with your message
git commit -m "feat(user-auth): implement OAuth2 login flow
- Add OAuth2 provider configuration
- Implement authorization code flow
- Store user tokens securely
- Add logout functionality
Closes #789"
Examples
Feature Addition
feat(dashboard): add real-time metrics display
Implement live updating charts for system performance metrics.
- Add WebSocket connection for real-time data
- Create reusable chart components
- Optimize data polling to reduce server load
- Add error handling for connection failures
Resolves #234
Bug Fix
fix(payment): resolve double-charge issue
Prevent duplicate payment processing when users refresh
the confirmation page. Added idempotency key validation
and improved error messaging.
Fixes #567
Documentation Update
docs(api): update webhook payload examples
Add comprehensive examples for all webhook event types
and clarify field descriptions. Include error response
examples and rate limiting information.
Refactoring
refactor(auth): extract user validation logic
Move user input validation to dedicated service class.
- Create UserValidationService with comprehensive rules
- Add unit tests for all validation scenarios
- Update existing controllers to use new service
- Improve error messages for validation failures
Breaking Change
feat(api): migrate to GraphQL API
Replace REST endpoints with GraphQL schema for improved
flexibility and reduced over-fetching.
BREAKING CHANGE: All REST API endpoints are deprecated.
Clients must migrate to GraphQL queries by v2.0.0.
Migration guide: docs.mysite.com/graphql-migration
Best Practices
Do's
- ✅ Keep subject lines under 50 characters
- ✅ Use conventional commit format when possible
- ✅ Explain the "why" behind changes, not just the "what"
- ✅ Reference related issues or pull requests
- ✅ Use bullet points for multi-part changes
- ✅ Review commit messages before pushing
Don'ts
- ❌ Write vague messages like "fix bug" or "update code"
- ❌ Include irrelevant details about your day or mood
- ❌ Use swear words or unprofessional language
- ❌ Commit large, unrelated changes together
- ❌ Forget to mention breaking changes
Team Consistency
- Establish conventions - Document your team's commit message standards
- Use templates - Create commit message templates for common scenarios
- Review process - Include commit message quality in code reviews
- Tools integration - Use commit hooks or CI to enforce standards
- Education - Train team members on best practices
Tools and Automation
Commit Message Linting
Use tools to enforce commit message standards:
# Install commitlint
npm install -g @commitlint/cli @commitlint/config-conventional
# Create .commitlintrc.js
module.exports = {
extends: ['@commitlint/config-conventional']
};
Git Hooks
Add pre-commit hooks to validate messages:
#!/bin/sh
# .git/hooks/commit-msg
commitlint < $1
Interactive Commit
Use git's interactive mode for complex commits:
# Stage changes interactively
git add -p
# Use commit with verbose flag
git commit -v
Common Patterns
For Different Project Types
Web Applications:
feat(ui): add dark mode toggle
fix(auth): prevent session timeout on mobile
perf(images): implement lazy loading for gallery
APIs:
feat(api): add rate limiting middleware
fix(validation): correct email regex pattern
docs(api): update OpenAPI specification
Infrastructure:
chore(deps): update Node.js to v18 LTS
ci(pipeline): add automated testing for PRs
build(docker): optimize image size by 40%
For Different Change Sizes
Small Changes:
fix(typo): correct variable name in user model
style(lint): fix eslint warnings in component
Large Changes:
feat(onboarding): implement complete user registration flow
- Add multi-step form with validation
- Integrate email verification service
- Create welcome email templates
- Add user preference settings
- Implement progress tracking
Part of epic #1234
File Structure
git-commit-messages/
├── SKILL.md # Main skill file with guidelines
├── README.md # Overview and usage guide
├── examples.md # Good and bad commit message examples
├── commit-generator.py # Python script for commit message generation
└── vscode-integration.md # VS Code integration guide