Clean Code deserves Clean Commit.
A minimalist git commit workflow designed to be simple, memorable, and universal. Clean Commit helps you write clear, consistent commit messages that make your project history easy to understand.
Note: This is a documented personal workflow I've refined over years of practice. While I use the term "Clean Commit workflow" to describe this standardized approach, it may evolve into a broader convention as others adopt and adapt it.
Install Clean Commit as a standalone skill for AI assistants. It includes its own instructions and works without Clean Workflow or another Clean skill. You can also use the convention manually with the guides below.
Use a Codex version with codex plugin support; installation and discovery
were verified with Codex CLI 0.158.0-alpha.2.1.
Git and a local repository are required to inspect changes or create commits. Message-only validation does not need GitHub access.
Install the stable version from main:
codex plugin marketplace add wgtechlabs/clean-commit --ref main
codex plugin add clean-commit@clean-commit
codex plugin list --marketplace clean-commit --jsonConfirm the plugin is installed and enabled, then start a new chat and invoke
$clean-commit. Installation alone does not authorize repository changes.
$clean-commit draft a message for my staged changes without committing
$clean-commit validate this message: 🔧 update (api): fix pagination
$clean-commit check whether my staged changes should be split into separate commits
Drafts describe the staged diff. Drafting and validation do not stage files, create commits, amend history, or push. The target repository's explicit commit convention takes precedence.
Load the entire skills/clean-commit/ folder using
your host's skill installation mechanism. The instructions are self-contained;
the host must still provide the tools required for the requested operation.
Other vendors' hosts have not been verified in this repository's test record.
Clean Workflow provides broader development, review, and delivery guidance. Choose this standalone plugin for Clean Commit alone. This repository owns the skill; updates to the broader bundle are maintained separately.
Refresh the configured marketplace and reinstall its plugin:
codex plugin marketplace upgrade clean-commit
codex plugin remove clean-commit@clean-commit
codex plugin add clean-commit@clean-commitStart a new chat after updating. To uninstall and remove its marketplace:
codex plugin remove clean-commit@clean-commit
codex plugin marketplace remove clean-commitTo test dev before promotion to main, first remove an existing installation
and same-named marketplace with the commands above, then run:
codex plugin marketplace add wgtechlabs/clean-commit --ref dev
codex plugin add clean-commit@clean-commitUse another branch or an existing tag instead of dev to test a specific ref.
For local development, use the absolute checkout path as the marketplace source
and omit --ref. Switch back to the stable installation commands after testing.
See skill verification for recorded installation
results, behavior scenarios, and verification limits.
The current installable package version is tracked in
.codex-plugin/plugin.json. The version badge at
the top of this README refers to the convention specification, not the plugin.
Pushes to main, including a merged promotion PR, run the
release workflow. It uses the same pinned
Release Build Flow Action
configuration as Clean Coding and Clean Code Review: plan the version, update
the plugin manifest, then commit CHANGELOG.md and publish a tag and GitHub
Release when a version bump is needed. Existing release tags determine the
next version; 0.1.0 is the initial version when no tags exist. Other package
manifests are not synchronized by this workflow.
This repository is the canonical source for clean-commit. Maintain its skill
alongside SPECIFICATION.md, which remains authoritative.
Keep instructions self-contained and check examples against the specification.
Downstream bundles should import a released skill directory and record its
version and source commit, rather than maintain independent edits. A bundle
can lag until its update is reviewed and merged.
Existing commit workflows 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
<emoji> <type>!: <description>
Example:
📦 new!: completely redesign authentication system
- Use lowercase for type
- Use
!immediately after type (no space) for breaking changes onnew,update,remove, orsecurity - Use present tense ("add" not "added")
- No period at the end
- Keep the complete subject at most 72 characters, including emoji, type, scope, and description
📦 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 workflow.
- 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 workflow: <emoji> <type>: <description> or <emoji> <type> (<scope>): <description>. Add ! after type for breaking changes (only for new, update, remove, security) e.g. <emoji> <type>!: <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 | 📦 new!: redesign authentication system"
}
]
}- 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 Workflow
Use Clean Commit workflow 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.