Commit Message Conventions
A commit message is the only durable, human-written explanation attached to a change — the diff shows what changed, but only the message explains why. Sloppy messages like 'fix' or 'wip' cost real time later: whoever runs git log, git blame, or writes a changelog months from now has nothing to go on but the message and the diff. Conventions exist to make that record consistently useful, both for humans skimming history and for tools that parse commit messages automatically to generate changelogs, determine semantic version bumps, or trigger release pipelines.
Cricket analogy: A commit message is like the radio commentator's explanation of why Ben Stokes chose to reverse-sweep a yorker — the scorecard shows the shot, but only the commentary explains the reasoning future analysts will rely on.
The classic seven rules
A widely cited baseline (originating from Tim Pope's influential blog post) is: separate subject from body with a blank line; limit the subject line to about 50 characters; capitalize the subject line; do not end the subject line with a period; use the imperative mood ('Add feature' not 'Added feature' or 'Adds feature'); wrap the body at about 72 characters; and use the body to explain what and why, not how (the diff already shows how). The imperative-mood rule has a memorable test: a well-formed subject line should complete the sentence 'If applied, this commit will ___.'
Cricket analogy: Like a strict scorecard style guide: keep the headline result short ('India win by six wickets'), capitalize player names, skip the trailing period, and write the match report below explaining strategy — not just restating the ball-by-ball.
# A well-formed commit message following the classic conventions
git commit -m "Add retry logic to payment webhook handler" -m "
The webhook handler previously failed permanently on transient
network errors from the payment provider, causing lost events.
This adds exponential backoff with up to 5 retries before the
event is moved to the dead-letter queue for manual inspection.
Fixes #742"
# git log --oneline shows just the subject lines, so they must
# stand alone and be scannable
git log --oneline -5
# a1b2c3d Add retry logic to payment webhook handler
# 9f8e7d6 Refactor webhook signature verification into shared helper
# 4c5d6e7 Fix off-by-one error in pagination cursorConventional Commits
Conventional Commits is a more formal, machine-parseable specification layered on top of the classic rules: <type>[optional scope]: <description>, where type is typically one of feat, fix, docs, style, refactor, perf, test, build, ci, or chore. A breaking change is flagged either with a ! after the type/scope (feat!:) or a BREAKING CHANGE: footer. Because the format is predictable, tools like semantic-release can parse commit history to automatically determine the next version number (a feat commit bumps the minor version, a fix bumps the patch version, a breaking change bumps the major version) and generate a changelog grouped by type, entirely without a human writing release notes by hand.
Cricket analogy: Like a strict match-report tagging system — 'century:', 'wicket:', 'rain-delay:' prefixes on every entry — so the league's stats engine can auto-update the season table and flag a 'career-best:' entry as headline news, without a human compiling it.
# Conventional Commits examples
git commit -m "feat(auth): add OAuth2 login via Google"
git commit -m "fix(parser): handle empty CSV header row without crashing"
git commit -m "docs: clarify installation steps for Windows"
git commit -m "refactor(cache): extract eviction policy into strategy interface"
# A breaking change, flagged two ways
git commit -m "feat(api)!: remove deprecated /v1/users endpoint"
git commit -m "feat(api): change response shape for /orders" -m "BREAKING CHANGE: 'total' is now a string to preserve decimal precision."Many teams enforce commit message conventions automatically with a commit-msg git hook (e.g. via commitlint) so malformed messages are rejected at commit time rather than caught — or missed — in review.
- Commit messages record why a change was made, information the diff alone cannot convey.
- Classic conventions: imperative mood, short capitalized subject line, blank line, wrapped body explaining what/why.
- Conventional Commits adds a structured
type(scope): descriptionformat that tools can parse. - feat, fix, and breaking-change markers in Conventional Commits can drive automatic semantic version bumps.
- Automated changelog generation depends on consistent, structured commit history.
- commit-msg hooks (e.g. commitlint) can enforce conventions automatically at commit time.
Practice what you learned
1. According to the classic commit message conventions, what mood should the subject line use?
2. In Conventional Commits, which type would be used for a commit that adds a brand-new feature?
3. How does Conventional Commits flag a breaking change?
4. What is the main practical benefit of structured commit messages like Conventional Commits for tooling?
5. What is a commit-msg hook commonly used for regarding commit conventions?
Was this page helpful?
You May Also Like
Viewing History with git log
Learn to inspect a repository's commit history using git log's filtering, formatting, and graph options to understand who changed what and why.
Committing Changes
How to create commits, write effective commit messages, and understand what a commit actually records in Git's history.
Pull Requests and Code Review
How pull requests turn a branch into a reviewable, discussable proposal for merging code, and the practices that make code review effective rather than a rubber stamp.
Git Tags and Releases
Understand how git tags mark specific commits as meaningful milestones like versions, and how lightweight vs annotated tags support release workflows and reproducible deployments.
Related Reading
Related Study Notes in Software Engineering
Browse all study notesMicroservices Study Notes
Software Architecture · 30 topics
Software EngineeringTesting & TDD Study Notes
Software Testing · 30 topics
Software EngineeringDesign Patterns Study Notes
Software Design · 30 topics
Software EngineeringSoftware Engineering Study Notes
Python · 75 topics
Software EngineeringSystem Design Study Notes
Architecture · 46 topics