On this page
How to Write a Good Git Commit Message
A good commit message states what changed and why in an imperative, one-line subject. Learn the format that keeps history useful.
Quick answer
- A good commit message has a short, imperative subject line that says what the change does and why.
- Write it as a command (“Add rate limiting”), not a description (“Added rate limiting”).
- The body explains why and any context, so future readers (including AI agents) don’t have to guess.
Why commit messages matter
The commit log is the first place anyone — you, a teammate, an AI assistant — goes to understand a change. A good message turns git log into documentation; a bad one turns it into noise. The quality of your history directly affects how effectively an AI agent can reason about your codebase later, since it reads commit context to understand intent.
The format
A widely used convention:
Subject line (≤ 72 chars, imperative, capitalized)
Optional body explaining what and why, wrapped at 72 chars.
Mention context the diff can't show: the bug, the trade-off, the alternative considered.Some teams add a type prefix, the “Conventional Commits” style: fix:, feat:, docs:, refactor:. For example, fix: validate email before sending verification. The prefix is optional but helps automation (changelogs, versioning).
Good vs bad
Bad: fixed stuff, wip, updated code, changes.
Good: fix: reject duplicate emails on registration, feat: add pagination to the orders endpoint, refactor: extract price calculation into a helper.
How to write it
Write the subject first, then the body if the change needs explaining. If you can’t summarize the change in one line, the change is probably too big — a signal to split it. Reference the issue or ticket number when you have one.
Where this bites vibecoders
AI assistants, left to themselves, generate commits like “update” or “fix bug” — or squash everything into one vague commit. Since good history is also good context for the next AI session, the habit of writing a real subject line is doubly valuable. Tell the assistant explicitly to write Conventional Commits, and you get useful history for free.
Where AI coding assistants get this wrong
- Writing vague subjects like “update” or “changes”.
- Mixing many unrelated changes into one commit.
- Using past tense or non-imperative phrasing.
- Omitting the why, which the diff can’t show.
Checklist
- Use an imperative, capitalized subject under 72 characters.
- Explain why in the body when the reason isn’t obvious.
- One logical change per commit.
- Follow a consistent convention (like Conventional Commits).
- Reference issues/tickets when available.
FAQ
Why imperative mood?
Git’s own tooling uses it (“Merge branch…”), and the convention frames the commit as a command to the codebase — “add X” — which reads naturally in git log and changelogs. It’s a convention, not a rule, but consistency is the point.
What are Conventional Commits?
A specification that prefixes the subject with a type — feat, fix, docs, refactor, and others — optionally with a scope. It enables tooling to auto-generate changelogs and determine version bumps from commit history.
How does this help AI agents?
Agents read commit history to understand what changed and why. Clear, single-purpose messages give them accurate context for reasoning about the codebase, reducing the chance they misinterpret a change. It’s a small input with outsized effect on agent quality.