How to Write Better Git Commit Messages

Why Commit Messages Matter

Your commit messages are the primary documentation of your project's history. Six months from now, someone (possibly you) will run `git log` to understand why a change was made. A good commit message answers the "why" — not the "what" (the diff shows the what).

The Seven Rules of a Great Commit Message

1. Separate subject from body with a blank line

Fix login validation error

The auth middleware was not checking token expiry for OAuth

providers. Added a JWT expiry check before the session lookup.

2. Limit the subject line to 50 characters

Short subjects are easier to scan in `git log --oneline`. If you cannot describe the change in 50 characters, the commit may be too broad.

3. Capitalize the subject line

`Add` not `add`, `Fix` not `fix`. This is a convention, not a rule — but consistency matters more than which convention you choose.

4. Do not end the subject with a period

Trailing periods add visual noise in compact log formats.

5. Use the imperative mood in the subject line

Write "Fix bug" not "Fixed bug" or "Fixes bug". Git itself uses the imperative: "Merge branch", "Rebase", "Reset". Think of it as completing the sentence "If applied, this commit will ..."

6. Wrap the body at 72 characters

This ensures readability in terminal and command-line tools. Most editors have a "hard wrap at 72" setting for commit messages.

7. Use the body to explain what and why, not how

Bad: Changed the timeout from 30 to 60 seconds

Good: Increase connection timeout for slow CI runners

The CI pipeline on the staging server frequently times out

during peak hours. Doubling the timeout reduces false

positive failures while keeping the upper bound reasonable.

Conventional Commits

Many teams adopt the **Conventional Commits** specification for structured messages:

feat: add user avatar upload

fix(auth): handle expired tokens correctly

docs: update API reference

refactor: extract payment validation to a service

chore: upgrade dependencies

This format enables automated changelog generation and semantic versioning.

Tools to Help

- `git commit --verbose` — shows the diff as you write your message

- `commitlint` — enforces commit message conventions in CI

- `git log --oneline --graph` — see how your messages look in context

A little effort on every commit message compounds into a valuable, readable history that your entire team (and your future self) will appreciate.