How to Write Good Commit Messages (and Why It Matters With AI)

Every time you save a snapshot of your project in Git — a commit — you write a short message describing it. Most beginners write update or fix stuff. Six months later, when something breaks and you're scrolling through history trying to find what changed, those messages are useless.

Good messages take ten extra seconds and turn your Git history into a searchable diary of your project. (Git and GitHub for Beginners covers commits themselves.)

What a commit message is for

A commit message answers one question for a future reader — often you: what changed, and why?

The what is visible in the code diff. The why is not. "Increase timeout to 30s" is readable from the code. "because the PDF export takes ~20s for large reports" isn't, and it's what stops someone lowering it again.

The format

Most teams use this shape:

Short summary of the change (under ~50 characters)

Optional longer explanation after a blank line. Say why the change
was needed and anything surprising about how it works. Wrap at
around 72 characters.

The rules for the summary line:

Imperative mood, like a command: "Add", "Fix", "Remove" — not "Added" or "Adds". Read it as "If applied, this commit will… Add password reset emails."
Short. Tools like GitHub cut long summaries off.
Specific. Name the thing that changed.
No full stop at the end.

Good and bad examples

❌ Unhelpful	✅ Helpful
`fix`	`Fix checkout crash when cart has a discount`
`update`	`Update Stripe SDK to fix webhook signature error`
`changes`	`Move API keys from frontend to server environment`
`wip`	`Add plant list page (no editing yet)`
`asdf`	`Remove unused image upload code`
`Fixed the thing Sarah mentioned`	`Show error when signup email is already taken`

Conventional Commits

Some projects use a prefix style called Conventional Commits:

feat: add password reset emails
fix: prevent double charge on checkout retry
docs: explain local setup in README
refactor: split PlantCard into smaller components
chore: update dependencies

It's optional. It helps when tools generate changelogs or version numbers automatically from commit history. (Semantic Versioning Explained.) If your project already uses it, follow it; if not, plain clear sentences are fine.

Commit small, commit often

A commit should be one logical change. "Add login, restyle homepage, and fix typo in footer" is three commits.

Small commits are easier to understand, easier to review, and — crucially — easier to undo. If the restyle breaks something, you can revert just that commit without losing login. (How to Undo Anything in Git.)

Commits when an AI tool is making the changes

AI coding tools can change dozens of files in minutes. That makes frequent commits more important, not less:

Commit before asking for a big change. It's your save point. If the result is a mess, you can go straight back.
Commit after each working step. "Login works" → commit. "Password reset works" → commit.
Review the diff before committing. Don't commit changes you haven't looked at. (How to Read a Diff.)
Never commit secrets. Check that no .env file or API key slipped in. (What Is .gitignore?.)

Letting Claude Code write the message

Claude Code writes good commit messages if you ask — it can see the whole diff, so it can summarise what changed. Try:

Commit these changes with a clear message explaining why, not just what.

Or put your preference in your project's CLAUDE.md so it applies every time:

## Git
- Commit messages: imperative summary under 50 chars, then a short "why" paragraph.
- One logical change per commit.

(How to Write a CLAUDE.md.) Still read the message before accepting it: the tool knows what changed, but only you may know why.

Fixing a bad message

Just made a commit with a bad message and haven't pushed yet?

git commit --amend -m "Fix checkout crash when cart has a discount"

If you've already pushed and others may have pulled it, leave it — rewriting shared history causes more trouble than a bad message.

EasySpawn connects each workspace to GitHub, so Claude Code's commits land on a branch you can review as a pull request before anything goes live. See how it works or join the waitlist.