Writing meaningful commit messages is crucial for maintaining a clean and understandable Git history. The Conventional Commits specification provides a structured way to write commit messages, making it easier to automate versioning, track changes, and collaborate effectively.
This guide covers all standard commit types, explaining their use cases and best practices.
Commit Types and Their Use Cases
1. feat: (Feature)
Used when introducing a new feature to the codebase.
✅ Example:
feat: add user authentication with JWT
Use Case:
- Adding new functionality, such as a login system.
- Implementing a new API endpoint.
2. fix: (Bug Fix)
Used for fixing a bug or resolving an issue.
✅ Example:
fix: correct password hashing logic
Use Case:
- Fixing a broken API call.
- Resolving an issue causing incorrect UI behavior.
3. chore: (Maintenance Task)
Used for project setup, configurations, or minor updates that do not change the application logic.
✅ Example:
chore: update dependencies to latest versions
Use Case:
- Updating third-party libraries.
- Configuring CI/CD pipelines.
- Renaming files without modifying code logic.
4. refactor: (Code Refactoring)
Used for modifying the code structure without changing functionality.
✅ Example:
refactor: optimize database query execution
Use Case:
- Improving code readability.
- Simplifying logic without changing behavior.
5. perf: (Performance Improvement)
Used when making changes that enhance performance.
✅ Example:
perf: reduce API response time by caching queries
Use Case:
- Optimizing database queries.
- Reducing page load times.
6. docs: (Documentation)
Used for updating or adding documentation.
✅ Example:
docs: add API usage examples to README
Use Case:
- Writing or updating README files.
- Adding inline code comments for clarity.
7. test: (Testing)
Used for adding or updating tests.
✅ Example:
test: add unit tests for authentication module
Use Case:
- Writing new test cases.
- Fixing or improving existing tests.
8. style: (Code Styling & Formatting)
Used for changes that do not affect the logic, such as formatting, whitespace, or semicolons.
✅ Example:
style: reformat code using Prettier
Use Case:
- Applying linting rules.
- Formatting code for consistency.
9. build: (Build System)
Used when making changes to build scripts, dependencies, or CI/CD configurations.
✅ Example:
build: update webpack configuration for production
Use Case:
- Configuring Webpack, Rollup, or Babel.
- Setting up Docker or Kubernetes.
10. ci: (Continuous Integration)
Used for changes related to CI/CD pipelines.
✅ Example:
ci: add GitHub Actions workflow for automated testing
Use Case:
- Adding CI/CD scripts.
- Modifying deployment pipelines.
11. revert: (Reverting Changes)
Used when rolling back a previous commit.
✅ Example:
revert: revert "feat: add social login"
Use Case:
- Undoing a faulty feature release.
- Rolling back breaking changes.
12. BREAKING CHANGE: (Major API or Behavior Changes)
Used to indicate changes that are not backward compatible.
✅ Example:
feat!: migrate database schema to v2
BREAKING CHANGE: Old database schema is no longer supported.
Use Case:
- Removing deprecated features.
- Changing API responses.
Best Practices for Writing Commit Messages
- Use imperative mood (e.g., "add feature" instead of "added feature").
- Keep the subject line within 50 characters.
- Add a detailed body if necessary (wrap lines at 72 characters).
- Reference related issues (e.g.,
fix: resolve login issue (#123)). - Avoid generic messages like "update code" or "fix bug."
Conclusion
Following the Conventional Commits standard helps maintain a structured commit history, making it easier to track changes, automate versioning, and collaborate efficiently.
By using clear and descriptive commit messages, teams can ensure that their repositories remain maintainable and understandable for everyone involved.
🚀 Start using Conventional Commits today and improve your Git workflow!
