Listening to
Git
Commit Messages
Writing clear, human and machine readable commit messages.
TRACTION
iamtraction
3 min readJan 12, 2018

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)]
  1. Type: Indicates the nature of the change (e.g., feat, fix, docs, etc.).
  2. Scope (optional): Provides extra contextual information, such as the affected subsystem or module.
  3. Description: A concise summary of what the commit does.
  4. Body (optional): A detailed explanation of the change and its motivation.
  5. 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:

KeywordChange TypeVersion Impact
buildBuild system changes
ciContinuous Integration adjustments
docsDocumentation changes
featNew feature introductionMINOR (v1.0.0 → v1.1.0)
fixBug fixesPATCH (v1.0.0 → v1.0.1)
perfPerformance improvementsBased on context
testAdding or correcting tests
refactorCode refactoringCould include BREAKING CHANGE
BREAKING CHANGEBreaking API or behavior changeMAJOR (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.

...
Logo
© 2025 - TRACTION