Commit message conventions

What you will learn

• Apply the Conventional Commits <type>(<scope>): <summary> structure, including what belongs in the body
• Understand why good commit messages make git bisect, git log, and CHANGELOG generation actually usable
• Spot common commit-message mistakes and know how to correct them during code review

Commit messages are long-term operational metadata, not just local notes.

Start with a problem

After a production incident you tried to trace which commit introduced the bug, but the history was a wall of "fix bug" and "update". git bisect landed on a commit you couldn't interpret, so the root cause took far longer to pin down than it should have.

A practical structure

<type>(<scope>): <summary>

In body text, include:

• why this changed
• what risk or follow-up remains

Before Commit

Define change scopeChoose type prefixWrite clear description

→git commit

Convention Result

Readable historyAuto categorizationDocs generation ready

A good message is not for yourself now, but for yourself in six months and your teammates.

Example

fix(auth): reject expired refresh token

Align backend token validation with new TTL rule.
Risk: may increase login retries for stale clients.

Team-level rules

1. start summaries with an action verb
2. explain motivation, not only file edits
3. mark breaking changes explicitly

!PR descriptions do not replace commit messages

PR context may be collapsed or lost over time. Commit history remains the durable searchable index.

Common misconceptions

1. "The message is just for me." The opposite is true. You and your teammates rely on git log and git bisect months later; vague messages double the cost of every future trace.
2. "One commit, several unrelated changes." Mixing a login fix with a typo fix means git revert / git bisect can't isolate one concern, skewing bisection results.
3. "Amend a commit that's already pushed." Rewriting shared history makes collaborators' pull conflict. Use --amend only for local, unpushed commits; for pushed ones, add a new corrective commit.
4. "Summary like fix: bug." No scope, no reason. The conventional form fix(auth): reject expired refresh token tells readers the blast radius at a glance.

!--amend rewrites, it does not undo

git commit --amend creates a new commit object and replaces HEAD. Once pushed, amending forks everyone else's history and forces a coordinated force-push.

A real incident trace

# Production login failure — find the offending commit
$ git log --oneline -10
a1b2c3d update      # no clue what changed
e4f5g6h fix bug     # equally uninformative
$ git bisect start <bad> <good>
# bisection stops at "update", but the message hides a broken token check

Had it been fix(auth): reject expired refresh token, the trace would have hit immediately and saved a long investigation.

Good follow-up reads

1. commit hygiene
2. prepare commits before pull request
3. small batch review

Try it yourself

1. Rewrite the last five commits of a project into Conventional Commits format (type(scope): summary + body with reason), then compare the readability of git log --oneline before and after.
2. Deliberately split a "login fix" and a "doc typo fix" into two commits, then run git bisect to feel why single-concern commits matter.
3. During review, take a fix: bug-style message and rewrite it using the template, explaining why scope and reason are both required.

Further reading

Keep going on the same topic:

• Advanced commit message conventions
• Conflict Resolution Routine
• Fetch-First Sync