How to Write Commit Messages That Don't Suck: A Practical Guide

“Fix bug.” “Update.” “Changes.” If these look familiar, this post is for you. Let’s transform your Git commit messages from cryptic notes into valuable documentation.

Introduction: The Unsung Hero of Version Control

Git commit messages are one ofthe most undervalued forms of documentation in software development. Too often, they are rushed, vague, or uninformative. Yet, well-crafted commit messages are a goldmine. They tell the story of your project’s evolution, help teammates understand changes, speed up debugging, and make git blame a friend rather than a foe.

This guide provides practical tips and conventions to help you and your team write commit messages that are clear, concise, and genuinely useful.

Why Bother with Good Commit Messages?

Investing a few extra moments to write a good commit message pays off significantly:

• Improved Team Communication: Clear messages help everyone understand the what and why of changes without having to dig through code.
• Faster Code Reviews: A good summary in the commit message can provide context that speeds up the review process.
• Easier Debugging: When a bug is traced back to a specific commit, a descriptive message can instantly clarify the intent of the change, making it easier to identify the problem.
• Simplified Release Notes: Well-structured commits can often be used to auto-generate or easily compile release notes.
• Better git log and git blame Output: Makes navigating project history and understanding contributions much more efficient.
• Onboarding New Team Members: A clean commit history helps new developers get up to speed on the project’s lifecycle and past decisions.

The Anatomy of a Great Commit Message

A widely adopted convention for commit messages is to structure them with a subject line and an optional body.

1. The Subject Line (The “What”):

• Keep it Short: Aim for 50 characters or less. Many tools and UIs truncate longer subjects.
• Use Imperative Mood: Write as if giving a command (e.g., “Fix login bug,” not “Fixed login bug” or “Fixes login bug”). This is a Git convention.
• Capitalize the First Letter: Just like a sentence.
• No Period at the End: Another Git convention.
• Be Specific: Avoid generic terms. “Refactor user authentication module” is better than “Code cleanup.”

2. The Body (The “Why” and “How”):

• Separate from Subject with a Blank Line: This is crucial for git log and other tools to parse correctly.
• Explain the Problem: Why was this change necessary? What issue does it address?
• Describe the Solution: How was the problem solved? What approach was taken?
• Wrap Lines at 72 Characters: This improves readability in terminals and various Git tools.
• Use Bullet Points for Lists: If explaining multiple related changes or impacts.
• Reference Issue Trackers: If the commit relates to a specific ticket (e.g., “Closes #123”), include it. Many platforms will automatically link these.

Bad Examples (And How to Fix Them)

Let’s look at some common anti-patterns:

• Bad: Fix bug

  • Why it’s bad: Which bug? How was it fixed?
  • Good: Fix: Prevent null pointer exception in user profile save
    • `
    • The user profile save operation could fail if the avatar field was empty,
    • leading to a NullPointerException.
    • This commit adds a null check before attempting to access avatar properties.
    • Closes #452
    • `

• Bad: Update code

  • Why it’s bad: Completely uninformative.
  • Good: Refactor: Simplify cart total calculation logic
    • `
    • Replaced the iterative sum in calculateCartTotal with a more efficient
    • reduce function. This improves readability and slightly enhances performance
    • for large carts.
    • `

• Bad: Changes to CSS and JS for new feature X that PM asked for last minute

  • Why it’s bad: Too long for a subject, includes unnecessary chatter.
  • Good: Feat: Add dark mode toggle to user settings page
    • `
    • Implements the dark mode feature requested by product management.
    • • Adds a toggle switch component to the user settings UI.
    • • Includes new CSS variables for dark theme colors.
    • • Updates JavaScript to handle theme switching and persistence in localStorage.
    • Relates to TICKET-789
    • `

Tips for Consistent, High-Quality Commits

• Commit Small, Logical Changes: Each commit should represent a single, atomic unit of work. This makes them easier to understand, review, and revert if necessary.
• Commit Often: Don’t wait until you have a mountain of changes to commit.
• Write Messages Before Committing Code (or as you go): This helps you think through the changes and ensures the message accurately reflects the work.
• Use a Linter/Formatter for Commit Messages: Tools like commitlint can help enforce conventions automatically.
• Team Agreement: Discuss and agree on commit message conventions as a team. Document them!
• Review Commit Messages During Code Reviews: Make it part of your standard review process.

Conclusion: Your Commits Are Your Project’s Diary

Treat your commit messages with the respect they deserve. They are not just a hoop to jump through; they are a vital part of your project’s history and a powerful tool for your team. By adopting clear, consistent, and informative commit message practices, you contribute to a more maintainable, understandable, and collaborative codebase.

What are your favorite commit message tips or pet peeves? Share them in the comments!