Best Practices for Writing Git Commit Messages

Write readable, meaningful commit messages that matter.

Git commit messages are the backbone of a project's history. Well-written messages clarify why changes were made, guide teammates, and simplify code review and debugging. However, unclear or inconsistent commit messages can obscure the development process and make collaboration difficult.

This article outlines best practices for writing git commit messages that ensure your history is readable, meaningful, and helpful to everyone involved.

Why Good Commit Messages Matter

  • Traceability: Understand why a change was made, not just what changed.
  • Collaboration: Help reviewers and future developers (including yourself!) understand decisions.
  • Reverts & Fixes: Quickly locate where and why bugs were introduced.
  • Release Notes: Easily compile changes for releases or changelogs.

The Anatomy of a Good Commit Message

Most projects benefit from a clear and consistent message structure. A recommended format:

<type>: <short summary, imperative, 50 characters or less>

<optional detailed description, wrapped at 72 characters>

Example

fix: prevent crash on null user profile

Previously, the app would crash if the profile object was null. 
This adds a null check and fallback, ensuring stability across sessions.

Key points:

  • Type: Optional, but helpful (e.g., feat, fix, chore, docs)
  • Short summary: Imperative mood (“fix bug,” not “fixed bug”)
  • Detailed body: Explains motivation, context, or side effects

Best Practices for Writing Commit Messages

1. Use the Imperative Mood

Write as if giving a command or request.

❌ “Fixed bug in login page”
✅ “Fix bug in login page”

This convention matches the style of auto-generated commits and aligns with commands like git revert or git merge.

2. Keep the Subject Brief but Descriptive

  • Limit to 50 characters.
  • Capitalize the first letter.
  • Don’t end with a period.

Why? Short subjects are easier to read in logs and quick overviews.

3. Separate Subject from Body with a Blank Line

This helps parsing tools and keeps messages readable.

Add search feature to product list

Implements basic full-text search using backend API. Updated
unit tests to cover search queries and error cases.

4. Explain the What and the Why

  • What did you change?
  • Why was it needed?

Don’t restate the code diff, focus on intention and reasoning.

5. Reference Issues and Related Work

Link to tickets or pull requests for context.

feat: add password reset flow

Closes #73. Follows the discussion in PR #62.

6. Be Consistent

Adopt a style guide (Conventional Commits, Angular Commit Message Guidelines, etc.) and use it throughout the project.

7. Proofread Your Messages

Typos in commit messages can be as problematic as code typos—proofreading helps ensure clarity.

Common Mistakes to Avoid

  • “WIP” or “update” commits: Be specific; avoid vague references.
  • Committing unrelated changes together: Keep commits atomic—one change per commit.
  • Repeating the code: Avoid describing exactly what’s visible in git diff.

Tools and Tips

  • Commitlint: Enforce conventions with automated tools.
  • git commit -v: Shows the diff as you write the commit message.
  • Interactive rebase: Squash, edit, and reorder commits for clarity before merging.

Summary

Writing meaningful git commit messages is a small act with a big payoff. Clear, concise, and consistent messages foster better collaboration, easier maintenance, and a healthier codebase.
Next time you commit, take that extra moment to explain the 'why'—your future self (and teammates) will thank you!

Write readable, meaningful commit messages that matter.

Back to All Articles