Guide
Git Commit Best Practices
A good commit message is the difference between a history you can navigate and one you dread. These rules apply regardless of which convention your team uses.
Stop writing commit messages manually
Paste your diff and let AI generate a best-practice message.
1. Use imperative mood
Write your subject line as if completing the sentence: “If applied, this commit will…” Git itself uses imperative mood in its own generated messages (Merge branch, Revert “…”).
Wrong
Fixed the login bugAdding user authenticationI changed the database schemaRight
Fix login bug in session handlerAdd user authenticationUpdate database schema for multi-tenancy2. Keep the subject line under 72 characters
Most git tools truncate at 72 characters in log views. GitHub wraps at 72. git log --oneline is unreadable when lines wrap. The 72-character limit forces clarity — if you can't describe the change in 72 characters, the commit is probably doing too much.
✓ feat(auth): add JWT refresh token rotation (44 chars)
✗ feat(auth): add JWT refresh token rotation and update the session management to handle the new token lifecycle properly (116 chars)
3. Explain why, not what
The diff shows what changed. The commit body should explain why you made the change — the business context, the bug that triggered it, the trade-off you made. Future you (or your colleague at 2am) will thank you.
fix(auth): increase bcrypt rounds from 10 to 12 Security audit flagged that bcrypt with 10 rounds completes in ~100ms on modern hardware — below the OWASP recommended 250ms threshold. Increasing to 12 rounds brings hashing time to ~400ms on our servers. No user-facing impact; existing password hashes remain valid. Ref: internal security audit #SA-2024-018
4. Commit one logical change at a time
Atomic commits make bisect work, make reverts safe, and make code review comprehensible. If your commit message requires “and” to describe it, split the commit.
Avoid
fix(api): fix auth bug, update deps, reformat user serviceBetter — three commits:
fix(api): handle missing auth header in middlewarechore(deps): upgrade express from 4.18 to 4.19style(user): run prettier on UserService5. Be specific
Vague commit messages are noise. Name the component, method, or file. If you fixed a bug, say where and what it caused.
Fix bugFix null check in UserService.authenticate()Update codeRefactor payment module to use Strategy patternAdd featureAdd CSV export to analytics dashboardFix testsFix flaky integration test in OrderController6. Enforce it with a hook
Good intentions break down under deadline pressure. Use a prepare-commit-msg hook to automate message generation, and a commit-msg hook to validate format. gitglossary.com generates the hook snippet automatically.