Guide to Write Better Git Commit Messages

As a software engineer, I’ve seen firsthand how good commit messages can make or break a codebase’s maintainability. Whether you're working solo or collaborating in a team of hundreds, writing clear, concise, and consistent commit messages is a sign of engineering maturity — and it pays dividends during code reviews, debugging, and audits.\n\nWhy Good Commit Messages Matter\n- Better collaboration: Teammates can understand the “why” behind changes at a glance.\n- Smoother reviews: Reviewers spend less time deciphering your intent.\n- Easier debugging: git blame, git bisect, and changelogs become far more useful.\n- Project hygiene: Clean history makes onboarding and audits faster and simpler.\n\n## The Anatomy of a Good Commit Message\nA well-written commit message typically has three parts:\nyaml\n<type>(<scope>): <short summary in imperative mood>\n\n<optional body that explains what and why, not how>\n\n<optional footer for issues, breaking changes, etc.>\n\n### 1. Use the Imperative Mood\nTreat the summary like a command:\n\n✅ Add user authentication middleware\n❌ Added user authentication middleware\n\nWhy imperative? It aligns with how Git reads it:\n\n If applied, this commit will add user authentication middleware\n\n### 2. Keep the Summary Line Short (≤ 50 chars)\nThink of it like an email subject line. It should:\n- Be concise\n- Summarize what the change does\n- Avoid vague phrases like “fix stuff” or “misc updates”\n\nExamples:\n- Fix broken redirect after login\n- Add API rate-limiting to prevent abuse\n- Refactor cart logic into separate module\n\n### 3. Add Context in the Body (If Needed)\nIf the what isn't obvious, explain the why or any gotchas:\nyaml\nFix broken redirect after login\n\nThe redirect middleware was failing when `req.session.returnTo` was undefined.\nThis change adds a fallback to `/dashboard` in such cases.\n\n\n### 4. Use Footers for Metadata\nFor issue tracking or breaking changes:\nyaml\nFix redirect issue\n\nResolves: #432\nBREAKING CHANGE: Login flow has changed for OAuth users\n\n\n### Commit Message Types\nUse commit “types” to categorize work:\n| Type | Purpose |\n| ---------- | -------------------------------------- |\n| feat | A new feature |\n| fix | A bug fix |\n| docs | Documentation only changes |\n| style | Formatting, missing semi-colons, etc. |\n| refactor | Code change that doesn’t fix a bug |\n| test | Adding or fixing tests |\n| chore | Maintenance tasks (e.g., build config) |\n\nExamples:\n- feat(auth): add JWT authentication support\n- fix(billing): handle null values in address\n- refactor(email): simplify service interface\n\n## Real Examples: The Good vs. The Bad\n| ✅ Good | ❌ Bad |\n| ---------------------------------------------- | --------------- |\n| fix(payment): handle 500 error from gateway | fix bug |\n| refactor(validation): extract logic to utils | code cleanup |\n| feat(editor): support markdown in comments | update editor |\n\nGreat commit messages are not about perfection — they’re about clarity and consistency. Think of them as your way of communicating with your future self, your teammates, and your tools.\n\nWhen in doubt, ask yourself:\n\n If I saw this message 6 months from now, would I know what changed and why?\n\nIf the answer is yes — you're doing it right.