Clean Code deserves Clean Commit.
A minimalist git commit convention designed to be simple, memorable, and universal. Clean Commit helps you write clear, consistent commit messages that make your project history easy to understand.
Existing commit conventions are too complex. They require memorizing lengthy type names, complex scoping rules, and rigid formats that slow you down.
Clean Commit is different:
- ✨ Simple: Only 9 types to remember
- 🎯 Visual: Emoji makes scanning history effortless
- 📝 Flexible: Works for any project size or type
- 🚀 Fast: No overthinking - just commit
| Emoji | Type | What it covers |
|---|---|---|
| 📦 | new |
Adding new features, files, or capabilities |
| 🔧 | update |
Changing existing code, refactoring, improvements |
| 🗑️ | remove |
Removing code, files, features, or dependencies |
| 🔒 | security |
Security fixes, patches, vulnerability resolutions |
| ⚙️ | setup |
Project configs, CI/CD, tooling, build systems |
| ☕ | chore |
Maintenance tasks, dependency updates, housekeeping |
| 🧪 | test |
Adding, updating, or fixing tests |
| 📖 | docs |
Documentation changes and updates |
| 🚀 | release |
Version releases and release preparation |
<emoji> <type>: <description>
Example:
📦 new: user authentication system
<emoji> <type>(<scope>): <description>
Example:
🔧 update(api): improve error handling
- Use lowercase for type
- Use present tense ("add" not "added")
- No period at the end
- Keep description under 72 characters
📦 new: login page with email validation
📦 new(api): endpoint for user registration
📦 new: dark mode theme support
🔧 update: improve database query performance
🔧 update(ui): enhance button hover animations
🔧 update: refactor payment processing logic
🗑️ remove: deprecated legacy authentication
🗑️ remove(deps): unused lodash dependency
🗑️ remove: obsolete migration scripts
🔒 security: patch XSS vulnerability in user input
🔒 security(auth): fix JWT token validation
🔒 security: update dependencies with known CVEs
⚙️ setup: add eslint configuration
⚙️ setup(ci): configure github actions workflow
⚙️ setup: initialize docker compose environment
☕ chore: update npm dependencies
☕ chore(deps): bump react to version 18
☕ chore: clean up unused imports
🧪 test: add unit tests for auth service
🧪 test(api): integration tests for user endpoints
🧪 test: fix flaky date parsing test
📖 docs: update installation instructions
📖 docs(api): add endpoint documentation
📖 docs: fix typos in contributing guide
🚀 release: version 1.0.0
🚀 release: prepare for 2.1.0 release
🚀 release: hotfix version 1.0.1
Scopes help specify where the change happened. They're completely optional but helpful in larger projects.
Good scopes:
- Component names:
(header),(footer),(navbar) - Module names:
(api),(database),(auth) - Feature areas:
(payments),(notifications),(search)
Keep scopes:
- Short (one word when possible)
- Lowercase
- Consistent across your project
Automate Clean Commit in VS Code by configuring GitHub Copilot to generate commit messages following this convention.
- Open VS Code Settings (JSON):
Ctrl/Cmd + Shift + P→ "Preferences: Open User Settings (JSON)" - Add this configuration:
{
"github.copilot.chat.commitMessageGeneration.instructions": [
{
"text": "Use Clean Commit convention: <emoji> <type>: <description> or <emoji> <type>(<scope>): <description>. Choose type: 📦 new=user-facing features/functionality, 🔧 update=modify existing code/logic, 🗑️ remove=delete code/features, 🔒 security=fix vulnerabilities, ⚙️ setup=configs/CI/tooling/.github files, ☕ chore=maintenance/deps/LICENSE, 🧪 test=test files, 📖 docs=README/guides/comments, 🚀 release=version tags. Format: lowercase type, present tense (add not added), no period, max 72 chars. Examples: ⚙️ setup: add GitHub funding configuration | 📦 new: user authentication | 🔧 update(api): improve error handling | ☕ chore(deps): bump react version"
}
]
}- Save and reload VS Code
- GitHub Copilot will now suggest commit messages using Clean Commit format
Alternative: Project-Specific Setup
Create .github/copilot-instructions.md in your repository:
# Commit Message Convention
Use Clean Commit convention for all commits.
See: https://github.com/wgtechlabs/clean-commitThis section shows real-world commit examples organized by project type to help you apply Clean Commit to your projects.
Context: A full-stack web app with React frontend and Node.js backend
📦 new: user profile page with avatar upload
📦 new(auth): social login with google and github
📦 new(dashboard): real-time analytics widgets
🔧 update(ui): improve mobile responsive layout
🔧 update: optimize image loading with lazy loading
🗑️ remove(ui): deprecated jquery legacy code
🔧 update: fix cart total calculation rounding error
🔧 update(form): improve validation error messages
🔧 update(api): handle network timeout gracefully
🔒 security: sanitize html input to prevent xss
🔒 security(session): implement csrf token validation
🧪 test(e2e): add cypress tests for checkout flow
🧪 test: increase coverage for payment module
📖 docs: update component usage examples
📖 docs(api): document authentication flow
☕ chore(deps): bump react from 17.0.2 to 18.2.0
☕ chore: update webpack to version 5
⚙️ setup(ci): add automated deployment pipeline
⚙️ setup: configure storybook for components
🚀 release: version 2.0.0
🚀 release: hotfix version 2.0.1 for login bug
Context: RESTful API service with database and authentication
📦 new(api): user registration endpoint with validation
📦 new: rate limiting middleware for api protection
📦 new(db): migration for orders table
📦 new(auth): jwt token refresh mechanism
🔧 update(api): improve error response format
🔧 update: optimize database query with indexing
🔧 update(middleware): refactor logging to use winston
🔒 security(api): add input validation to prevent injection
🔒 security: hash passwords with bcrypt instead of md5
🔒 security(auth): fix authorization bypass in admin routes
🔧 update: implement connection pooling for database
🔧 update(cache): add redis caching for frequent queries
📦 new(db): add full-text search indexes
🔧 update(db): optimize user query performance
🗑️ remove(db): drop unused legacy tables
⚙️ setup(docker): containerize application with compose
⚙️ setup: configure automated database backups
🧪 test(api): integration tests for auth endpoints
🧪 test: add load testing with artillery
📖 docs(api): generate swagger documentation
📖 docs: add architecture decision records
☕ chore(deps): update express to latest security patch
☕ chore: clean up deprecated api endpoints
🚀 release: version 3.1.0 with new features
Context: JavaScript/TypeScript library for developers
📦 new: add async/await support to all methods
📦 new(api): client method for batch operations
📦 new: typescript type definitions
🔧 update: improve error handling with custom errors
🔧 update: refactor core module for better performance
🗑️ remove: deprecated callback-based api
🔧 update(api): simplify configuration options
🔧 update: change default timeout to 30 seconds
📖 docs(breaking): document v3 migration guide
🚀 release: version 3.0.0 with breaking changes
📦 new: add debug mode for troubleshooting
🔧 update: improve error messages with actionable hints
📖 docs: add interactive examples to readme
📖 docs(api): document all public methods with jsdoc
📖 docs: create getting started tutorial
🧪 test: add unit tests for all core modules
🧪 test: achieve 95% code coverage
⚙️ setup: configure automatic type checking
⚙️ setup(ci): add automated npm publishing
☕ chore: update dependencies to latest stable
📦 new: add esm module support
📦 new: add umd bundle for browsers
⚙️ setup(build): optimize bundle size with rollup
🚀 release: publish version 2.5.0 to npm
Context: Command-line tool built with Node.js
📦 new: add init command for project setup
📦 new(cmd): deploy command with progress bar
📦 new: interactive configuration wizard
🔧 update(cli): improve help text formatting
🔧 update: add colorized output for better readability
🗑️ remove: deprecated --legacy flag
📦 new: add autocomplete support for bash and zsh
📦 new(ui): spinner animation for long operations
🔧 update: improve error messages with suggestions
🔧 update(config): support yaml and json config files
📖 docs: add command examples to help text
⚙️ setup: add installation script for multiple platforms
⚙️ setup(ci): automate binary builds for releases
📦 new: support installation via homebrew
📦 new: add windows installer
🚀 release: version 1.0.0 stable release
🧪 test: add integration tests for all commands
🧪 test(cmd): test deploy command with mocked api
📦 new(debug): add verbose flag for troubleshooting
☕ chore(deps): update commander to latest version
📖 docs: create comprehensive usage guide
📖 docs(examples): add real-world workflow examples
📖 docs: add troubleshooting section
📖 docs(install): platform-specific installation guides
Context: Chat bot with commands and event handlers
📦 new(cmd): welcome command for new members
📦 new: moderation commands for admins
📦 new(cmd): poll creation with reaction voting
🔧 update: improve help command with categories
🔧 update(cmd): enhance music player with queue system
🗑️ remove: deprecated legacy command syntax
📦 new: integration with spotify api
📦 new(feature): automated role assignment
📦 new: custom embed messages with rich formatting
🔧 update: improve message parsing and validation
🔧 update(db): migrate to postgresql for better scaling
📦 new(event): handle member join events
📦 new: reaction role system
🔧 update(event): improve message deletion logging
🔧 update: add rate limiting for command usage
🔒 security: validate user permissions before commands
⚙️ setup: add environment variable configuration
⚙️ setup(deploy): containerize bot with docker
📦 new(config): per-server configuration system
☕ chore: update discord.js to latest version
🧪 test: add unit tests for command handlers
🧪 test: mock discord api for integration tests
📖 docs: create bot setup guide for server admins
📖 docs(commands): document all available commands
🚀 release: deploy version 2.0.0 to production
Context: Custom GitHub Action for CI/CD workflows
📦 new: initial action for code quality checks
📦 new(input): add customizable threshold options
📦 new: support for multiple programming languages
🔧 update: improve performance of file scanning
🔧 update(output): add detailed report generation
🗑️ remove: legacy node 12 support
📦 new: add support for pull request comments
📦 new(integration): slack notification output
🔧 update: support both github token and app auth
🔧 update: improve error handling with actionable messages
⚙️ setup(ci): add automated testing workflow
📖 docs: create comprehensive action usage guide
📖 docs(examples): add workflow examples for common scenarios
📖 docs: add troubleshooting section
📖 docs(inputs): document all input parameters
📖 docs(outputs): document all output values
⚙️ setup: configure automated release process
⚙️ setup(build): optimize action bundle size
🚀 release: version 1.0.0 stable release
🚀 release: tag v2 for breaking changes
☕ chore(deps): update action dependencies
🧪 test: add end-to-end tests with real workflows
🧪 test(unit): test action logic with various inputs
🔒 security: validate and sanitize user inputs
☕ chore: update action to use node 20
Copy these templates to integrate Clean Commit with AI coding assistants.
Copy examples/copilot.instructions.md to your project:
mkdir -p .github/instructions
curl -o .github/instructions/copilot.instructions.md https://raw.githubusercontent.com/wgtechlabs/clean-commit/main/examples/copilot.instructions.mdCopy examples/AGENTS.md to your project root:
curl -o AGENTS.md https://raw.githubusercontent.com/wgtechlabs/clean-commit/main/examples/AGENTS.md- 📋 SPECIFICATION.md - Full technical specification with detailed guidelines
- 📄 QUICK-REFERENCE.md - Single-page cheatsheet for quick lookup
We welcome contributions! Please read our Contributing Guidelines to get started.
MIT License - see the LICENSE file for details.
Created with ❤️ by Waren Gonzaga / WG Tech Labs
Clean Code deserves Clean Commit.
