How to Write Good Git Commit Messages (With Examples)

A commit message is the only documentation that is guaranteed to travel with a change. Six months from now, git log and git blame are how you and your teammates will work out why a line of code exists. A message like "fix stuff" tells that future reader nothing; a good one saves them an hour.

The anatomy of a good commit message

Most well-regarded conventions agree on the same shape: a short subject line, a blank line, and an optional body that explains the motivation.

Fix race condition in session refresh

Two tabs refreshing at the same time could each issue a new token,
invalidating the other's session. Take a lock around the refresh call
and reuse the in-flight promise.

Fixes #412

Rules worth following

• Keep the subject around 50 characters and wrap the body at about 72. Tools like git log --oneline and GitHub truncate long subjects.
• Use the imperative mood: "Add retry logic", not "Added retry logic". A good test is whether the subject completes the sentence "If applied, this commit will ...".
• Do not end the subject with a period; it wastes a character and adds no meaning.
• Explain why, not just what. The diff already shows what changed; the message should record the reason, the trade-offs, and what you considered and rejected.
• Reference issues or tickets in a footer so history links back to the discussion.
• One logical change per commit. If you need the word "and" in the subject, you probably have two commits.

Before and after

Vague messages are the most common problem. Compare:

Bad:   update code
Bad:   fixes
Bad:   WIP

Good:  Validate email before creating invite
Good:  Cache user permissions for 60s to cut DB load
Good:  Remove deprecated v1 export endpoint

When the subject is not enough

For a typo fix, a one-line subject is fine. For anything that changes behaviour, add a body. Describe the problem, why this approach was chosen, and any side effects a reviewer or future maintainer should know about. Two or three sentences is usually plenty.

Make it a habit, not a chore

The hard part is not knowing the rules; it is following them at 6 p.m. after a long debugging session. Two things help: stage changes in small, focused chunks so the message is easy to write, and let a tool draft the first version. GitusAI reads your staged diff inside VS Code and proposes a message in your chosen style, which you can edit before committing. You still own the final wording; the tool just removes the blank-page problem.