gitshare

How to Write Git Commit Messages That Actually Help Your Team

Ali Soukarieh

— 4 min read
Code displayed on a laptop screen in a dark environment

You are staring at a Git log full of messages like "fix stuff," "wip," and "final final v2." Sound familiar? Bad commit messages are one of the most common (and most avoidable) sources of friction on development teams. When something breaks in production and you need to trace the change that caused it, a meaningful commit history is the difference between a 10-minute fix and a two-hour archaeology expedition.

Good commit messages are not about being formal or verbose. They are about making your future self — and your teammates — understand why a change was made without having to re-read every line of the diff.

Why Commit Messages Matter More Than You Think

Commit messages are documentation that lives inside your codebase. Unlike comments or README files, they are tied directly to specific changes, making them the most granular form of project history you have.

Here is where they show up and why they matter:

  • Code reviews: Reviewers read your commit message before your code. A clear message sets context and reduces back-and-forth questions.
  • Debugging: Running git bisect or git log --oneline becomes useful only when messages describe what changed and why.
  • Onboarding: New team members reading the Git log can understand how the project evolved — if the messages are coherent.
  • Changelog generation: Many teams auto-generate release notes from commit messages. Garbage in, garbage out.

A 2022 survey by GitClear found that code churn — reverted or quickly rewritten code — increased significantly year over year, partly attributed to poor documentation practices around changes. Clear commit messages help teams catch issues before they compound.

The Anatomy of a Good Commit Message

The most widely adopted convention follows a simple structure:

Short summary (50 characters or less)

Longer explanation of the change if needed. Wrap at 72 characters.
Explain the *why*, not just the *what*. The diff already shows what changed.

The first line is the subject. Think of it as an email subject line — it should make sense on its own when scanning a log. The body is optional but valuable for non-trivial changes.

Rules that help:

  1. Use the imperative mood. Write "Add validation for email input" not "Added validation" or "Adds validation." This matches Git's own conventions (e.g., "Merge branch...").
  2. Capitalize the subject line. Treat it like a sentence.
  3. Do not end the subject with a period. Space is precious in a 50-character limit.
  4. Separate subject from body with a blank line. Tools like git log --oneline rely on this.
  5. Explain why, not what. The diff shows what changed. The message should explain the reasoning or context.

Conventional Commits: Adding Structure at Scale

For teams that want more consistency, the Conventional Commits specification adds a lightweight prefix system:

feat: add dark mode toggle to settings page
fix: resolve null pointer in user profile fetch
docs: update API authentication guide
refactor: extract payment logic into service class
test: add integration tests for checkout flow

The prefix categorizes the change instantly. This is not just cosmetic — tooling like semantic-release and standard-version can parse these prefixes to automate versioning and changelog generation. A feat: commit bumps the minor version. A fix: bumps the patch. A commit with BREAKING CHANGE in the footer bumps the major version.

You do not need to adopt the full spec on day one. Start with just the prefix convention and add scopes or footers as your team matures.

Common Anti-Patterns and How to Fix Them

These are the commit message habits that hurt teams the most:

  • "Fix bug" — Which bug? Where? Why did it happen? Rewrite as: fix: prevent duplicate form submission on slow connections
  • "WIP" — Work-in-progress commits are fine locally, but squash or reword them before merging. Use git rebase -i to clean up.
  • "Update file.js" — The filename is already in the diff. Describe the behavior change: refactor: simplify error handling in file.js
  • One giant commit — If your commit message needs five bullet points, the commit is too big. Break it into logical units.
  • Copy-pasting ticket numbers as the entire message — "JIRA-1234" tells you nothing without opening the ticket. Reference the ticket, but write a human-readable summary too: fix: correct timezone offset in scheduling (JIRA-1234)

Enforcing Good Messages With Tooling

Relying on willpower alone does not scale. Here are tools that help enforce commit message quality:

  • commitlint: A linter that checks commit messages against a configurable ruleset (commonly paired with Conventional Commits). Runs as a Git hook via Husky.
  • Husky + lint-staged: Set up a commit-msg hook that rejects messages not matching your format.
  • Git templates: Run git config commit.template ~/.gitmessage to set a default template that reminds developers of your conventions every time they commit.
  • CI checks: Add a pipeline step that validates commit messages on pull requests. This catches anything that slipped past local hooks.

A simple .gitmessage template might look like:

# <type>: <subject> (50 chars max)
#
# What does this change do and why?
#
# Refs: #issue-number

Making It Stick: Team Adoption Tips

Introducing commit message conventions to an existing team requires a light touch. Here is what works:

  1. Document your convention in CONTRIBUTING.md. Keep it short — a few examples are worth more than a page of rules.
  2. Start with new repos or projects. Retrofitting conventions onto a messy history is demoralizing. Start fresh where you can.
  3. Review commit messages in PRs. Make it part of code review culture. A quick "Can you reword this commit?" normalizes the practice.
  4. Lead by example. If senior developers write thoughtful commit messages, juniors follow.
  5. Do not be pedantic. The goal is clarity, not perfection. A slightly imperfect message that describes the change is infinitely better than "fix."

Your Git history is a shared resource. Treat it with the same care you would treat your codebase, because six months from now, it might be the only thing standing between you and a mystery bug.

If you are sharing private repositories with teammates, recruiters, or clients, a clean commit history makes an even stronger impression. GitShare lets you generate shareable links for private repos — no GitHub account required for viewers — so your well-crafted commits get seen by the right people.

Read more