Conventional Commits Guide
Understand Conventional Commits, standardized Git commit messages, semantic versioning and automated changelog generation.
Conventional Commits is a standardized specification for writing Git commit messages. It defines a predictable format that makes commit history easier to understand for both developers and automated tools. By following the specification, teams can generate changelogs automatically, simplify release management and integrate commit history with semantic versioning workflows.
The specification is simple to learn yet powerful enough to support large software projects where consistent commit messages improve collaboration and automation.
What Are Conventional Commits?
A Conventional Commit begins with a commit type followed by an optional scope, a colon and a concise description. The commit type indicates the purpose of the change, making Git history more structured and easier to analyze.
type(scope): short descriptionBasic Examples
feat(auth): add password reset
fix(api): handle invalid responses
docs: update installation guide
refactor(ui): simplify navigation
test: add unit tests for login
chore: update dependenciesWhy Use Conventional Commits?
Using a consistent commit format improves project history and enables tooling that can automatically determine release versions, generate release notes and build changelogs from Git commits.
- Create consistent commit history.
- Support automated changelogs.
- Enable semantic versioning workflows.
- Improve code reviews.
- Simplify collaboration across teams.
Commit Structure
Every Conventional Commit contains a required type and description. The scope and body are optional, while a footer can provide metadata such as breaking changes or issue references.
type(scope): description
Optional body
Optional footerMost Common Commit Types
| Type | Purpose |
|---|---|
| feat | Introduce a new feature |
| fix | Fix a bug |
| docs | Documentation changes |
| style | Formatting only |
| refactor | Code improvements without behavior changes |
| test | Add or update tests |
| chore | Maintenance tasks |
| build | Build system changes |
| ci | Continuous integration changes |
| perf | Performance improvements |
Using Scopes
The optional scope identifies the area of the project affected by the commit. Scopes are especially useful in large repositories because they quickly show where changes occurred.
| Commit | Meaning |
|---|---|
| feat(auth) | Authentication feature |
| fix(api) | API bug fix |
| docs(readme) | README documentation |
| refactor(ui) | User interface refactoring |
Breaking Changes
One of the most valuable features of Conventional Commits is the ability to explicitly identify breaking changes. This allows automation tools to recognize when a new major version should be released according to Semantic Versioning (SemVer).
feat(api)!: remove legacy authentication endpoint
BREAKING CHANGE: The old authentication API has been removed.Conventional Commits and Semantic Versioning
Many release automation tools map commit types to semantic version increments. While project-specific rules may vary, the following mapping is commonly used.
| Commit Type | Typical Version Impact |
|---|---|
| fix | Patch version |
| feat | Minor version |
| Breaking change | Major version |
Commit Body
The commit body is optional but recommended for complex changes. It explains the motivation behind the change, implementation decisions or important context that is not obvious from the code itself.
Commit Footer
The footer can reference issues, pull requests or breaking changes. It provides structured metadata that many Git hosting platforms and automation tools can process.
fix(login): prevent duplicate sessions
Closes #248Automation Benefits
Because Conventional Commits follow a predictable format, many development tools can analyze Git history automatically. This reduces manual work during releases and improves consistency across software projects.
| Automation | Benefit |
|---|---|
| Changelog generation | Summarizes commits automatically |
| Release notes | Creates version summaries |
| Semantic versioning | Determines version increments |
| CI/CD pipelines | Supports automated release workflows |
Example Commit History
feat(auth): add OAuth login
fix(api): handle timeout responses
docs: improve deployment guide
refactor(ui): simplify navigation menu
perf(images): optimize image loading
test(api): add integration testsWhen Conventional Commits Are Most Useful
The specification is particularly valuable for teams, open-source projects and applications with regular releases. However, even individual developers benefit from a structured and searchable Git history.
- Team collaboration.
- Open-source repositories.
- Large applications.
- Automated release pipelines.
- Projects using Semantic Versioning.
Common Mistakes
The Conventional Commits specification is intentionally simple, but inconsistent usage can reduce its value for both developers and automation tools. Following the standard consistently is more important than using every optional feature.
- Using the wrong commit type for a change.
- Writing vague descriptions such as 'update' or 'fix stuff'.
- Creating inconsistent scope names across the project.
- Combining unrelated changes into a single commit.
- Forgetting to mark breaking changes.
- Using custom commit types that automation tools do not recognize.
Best Practices
- Use standard commit types whenever possible.
- Write concise descriptions in the imperative mood.
- Keep commits focused on a single logical change.
- Choose short, consistent scope names.
- Mark breaking changes explicitly using ! or a BREAKING CHANGE footer.
- Follow the same commit conventions across the entire team.
Frequently Asked Questions
What are Conventional Commits?
Conventional Commits are a standardized format for Git commit messages that uses commit types such as feat, fix and docs to describe the purpose of each change in a consistent way.
Do I have to use scopes?
No. Scopes are optional, but they are useful for identifying the part of the project affected by a commit, especially in larger repositories.
How are breaking changes indicated?
Breaking changes can be marked by adding an exclamation mark after the type or scope, or by including a BREAKING CHANGE footer in the commit message.
Why are Conventional Commits useful?
They create a predictable commit history, simplify collaboration and enable automation tools to generate changelogs, release notes and semantic version numbers from Git history.
Can I use Conventional Commits in personal projects?
Yes. Even for solo projects, the specification creates a cleaner Git history and makes it easier to understand past changes as the project grows.
Helpful Git Tools
A Conventional Commit Generator creates correctly formatted commit messages following the specification, a Git Commit Generator helps write clear and descriptive commits, a Semantic Version Calculator determines version increments based on release rules, a Release Notes Generator converts commit history into organized release summaries, and a Changelog Generator automatically builds readable changelogs from Conventional Commit messages.
Conclusion
Conventional Commits provide a simple but powerful standard for organizing Git history. By using consistent commit types, descriptive messages and explicit breaking change indicators, developers create commit histories that are easier to read, review and automate. Whether you work on a personal project, contribute to open source or develop enterprise software, adopting Conventional Commits improves collaboration, supports Semantic Versioning and makes release management significantly more efficient.