Git Commit Messages: Best Practices and the Conventional Commits Standard
Write commit messages that tell the full story of your codebase history with practical examples and the Conventional Commits specification.
Why Commit Messages Matter
Every git commit is a timestamped note to your future self and your team. The quality of commit messages directly impacts how fast bugs get diagnosed, how confidently teams merge code, and how automated changelogs are generated.
---
The Anatomy of a Great Commit Message
<type>(<scope>): <short summary>
<body - optional>
<footer - optional>The 50/72 Rule: Subject line max 50 characters. Body lines max 72 characters.
---
The Conventional Commits Standard
Types
| Type | When to Use |
|---|---|
| feat | A new feature |
| fix | A bug fix |
| docs | Documentation only changes |
| style | Formatting, no logic change |
| refactor | Code restructuring |
| perf | Performance improvements |
| test | Adding or correcting tests |
| chore | Build process, dependency updates |
Real Examples
feat(auth): add OAuth2 login with Google
Implements OAuth2 flow using Passport.js strategy.
Users can now sign in with Google accounts.
Closes #127fix(cart): prevent duplicate items when clicking add quickly
Debounced the add-to-cart button handler by 300ms
to prevent race condition in the useCart hook.
Fixes #203---
Breaking Changes
feat!: remove deprecated v1 API endpoints
BREAKING CHANGE: The /api/v1/ endpoints have been removed.
Migrate to /api/v2/ before upgrading.---
Common Mistakes
Vague Messages:
- Bad: fix bug, update stuff, WIP, cleanup
- Good: fix(checkout): resolve payment failure on Safari iOS 16
Past tense instead of imperative mood:
- Bad: Fixed login bug, Added caching
- Good: fix login bug, add caching layer
Explaining WHAT instead of WHY:
- Bad: refactor: move user validation to utils.ts
- Good: refactor: extract user validation to share logic between endpoints, reducing duplication
---
Automated Changelogs
The real power of conventional commits: tools like semantic-release can automatically determine next version number, generate CHANGELOG.md, create GitHub releases, and publish packages.
- feat → minor version bump (1.0.0 → 1.1.0)
- fix → patch version bump (1.0.0 → 1.0.1)
- feat! → major version bump (1.0.0 → 2.0.0)
---
Conclusion
Good commit messages transform a list of code changes into a coherent story. Adopt Conventional Commits, enforce it with commitlint, and watch your code reviews and debugging sessions become dramatically faster.
Try Toolifia's Interactive Tools for Free
No registration, no daily caps. Fast, client-side processing directly in your browser.