Conventional Commits is a specification designed to infuse clear, human and machine readable meaning into your commit messages. By establishing a uniform format, teams can streamline communication, automate release processes, and generate detailed changelogs without the usual hassle.
A well-structured commit message can transform how your team interacts with the codebase by:
- Enhancing Clarity and Consistency: Clearly defined commit messages improve shared understanding across the team.
- Enabling Automation: Tools can automatically generate CHANGELOGs, calculate semantic version bumps, and trigger build processes based on commit type.
- Facilitating Collaboration: When everyone follows the same guidelines, it's easier to track changes, debug issues, and maintain historical context.
Commit Structure
The commit message should be structured with two mandatory and three optional parts:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
- Type: Indicates the nature of the change (e.g.,
feat,fix,docs, etc.). - Scope (optional): Provides extra contextual information, such as the affected subsystem or module.
- Description: A concise summary of what the commit does.
- Body (optional): A detailed explanation of the change and its motivation.
- Footer(s) (optional): Information about breaking changes or issues that the commit addresses.
Semantic Versioning
The keyword you use for each commit type conveys specific meaning and often correlates with Semantic Versioning:
| Keyword | Change Type | Version Impact |
|---|---|---|
| build | Build system changes | |
| ci | Continuous Integration adjustments | |
| docs | Documentation changes | |
| feat | New feature introduction | MINOR (v1.0.0 → v1.1.0) |
| fix | Bug fixes | PATCH (v1.0.0 → v1.0.1) |
| perf | Performance improvements | Based on context |
| test | Adding or correcting tests | |
| refactor | Code refactoring | Could include BREAKING CHANGE |
| BREAKING CHANGE | Breaking API or behavior change | MAJOR (v1.0.0 → v2.0.0) |
Breaking changes can either be indicated in the footer with BREAKING CHANGE: or by appending an exclamation mark (!) right after the type or scope.
Examples
A Bug Fix
A simple bug fix might be committed as:
git commit -m "fix: broken home link"
A New Feature with a Scope
For additional clarity, you can include a scope:
git commit -m "feat(user-profile): add user-avatar API endpoint"
A New Feature with a Breaking Change
When introducing a new feature that includes a breaking change, you can use multiline commit messages.
git commit -m "feat: add user-data API endpoint
BREAKING CHANGE: remove user-name endpoint"
You can also signal a breaking change in single line commit messages:
git commit -m "chore!: drop support for Node 16"
A Bug Fix with an Explanation and Reference
You can also use multiline commit messages to describe the exact changes your commit is introducing and reference the issues it's addressing.
git commit -m "fix(auth): issue with Sign-in with Apple
The issue was caused by a mismatch in the expected token
claims during authentication. This fix ensures proper validation
and mapping of the Apple ID token claims, restoring login
functionality for affected users.
Closes: #1024"
Adopting a consistent Git commit message convention is more than just style. It's about fostering robust communication and paving the way for easier maintenance and automated tooling. As your team and codebase evolve, these practices become the backbone of an agile, responsive development process.
