Last updated
Commit Message Best Practices
- Subject line: 50 characters or less, imperative mood ("Add" not "Added")
- Blank line between subject and body — required for git log to format correctly
- Body lines: wrap at 72 characters
- Body explains what and why, not how (the code shows how)
- Always reference the issue/ticket number when one exists
- Use BREAKING CHANGE footer for any change that breaks backward compatibility
- One logical change per commit — split large changes into multiple commits
Examples
Example 1: Conventional Commits Format
The standard format is: type(scope): description
Types and when to use them:
feat → new feature for the user
fix → bug fix for the user
docs → documentation changes only
style → formatting, missing semicolons (no logic change)
refactor → code change that is neither a fix nor a feature
test → adding or updating tests
chore → build process, dependency updates, tooling
perf → performance improvement
ci → CI/CD configuration changes
revert → reverts a previous commit
Example 2: Feature Commit Messages
# Simple feature
feat(auth): add OAuth login with Google
# Feature with body explaining why
feat(auth): add OAuth login with Google
Users have been requesting social login for months. This reduces
friction in the signup flow and is expected to improve conversion
by ~15% based on A/B test data from similar features.
Closes #234
# Feature with breaking change
feat(api)!: change user endpoint response format
BREAKING CHANGE: The /api/users endpoint now returns a paginated
response object instead of a plain array. Clients must update to
handle the new { data: [], meta: { total, page, perPage } } format.
Migration guide: https://docs.example.com/migration/v3
Closes #189
Example 3: Bug Fix Commit Messages
# Simple fix
fix(auth): resolve null pointer exception when email field is empty
# Fix with context
fix(checkout): correct total calculation when discount code applied
The discount was being applied before tax calculation, resulting in
incorrect totals when both a discount code and taxable items were
present in the cart.
Fixes #567
# Hotfix
fix(payment): prevent duplicate charge on network timeout
When the payment gateway timed out, the retry logic was not checking
if the original charge had already been processed, causing duplicate
charges. Added idempotency key to all payment requests.
Fixes #891