Writing commit messages people can read

Who actually reads them

Three groups:

• You in six months, working out why something was done this way.
• Colleagues reviewing your changes.
• Employers who opened your repository before an interview.

Many people forget the last one. Commit history is part of a portfolio, and it shows how someone works.

What's wrong with "fix"

A message should answer "what changed and why". "fix", "update", "changes", "tweaks" answer nothing.

The test is simple: if in six months the message can't tell you whether this commit is worth opening, the message is bad.

The shape

First line — what was done, up to about seventy characters. A verb, no full stop at the end.

Bad:

fix
changes
working on the form

Good:

add amount validation to the expense form
fix crash on an empty notes list
remove a redundant database query from the orders list

Then a blank line and details, if needed. Here you explain not what but why: what the problem was, why this approach, what remains.

Details aren't always necessary. For an obvious change, the first line suffices.

On conventional prefixes

Many teams mark the type of change at the start:

feat: add expense export to a file
fix: correct the monthly total calculation
docs: describe how to run the project in the README

Not compulsory, but it looks tidy and tells the reader what to expect. Working in a team, agree on it at the start.

Splitting the work

The rule: one commit, one finished thought.

Bad: a single commit adding a feature, renaming variables across the file, and updating the documentation. It can't be reviewed and can't be reverted in parts.

Good: three separate commits.

How to get there: commit when you've finished a piece, not when you've finished the day. If you catch yourself writing "and also fixed", that's two commits.

What shouldn't appear

• Swearing and emotion. Even when the code really is dreadful.
• Personal data and passwords.
• Empty messages such as a dot or a space.
• Three languages mixed together. Pick one and stick to it.

What it gives you at interview

An employer opening your repository sees from the history whether you worked steadily or built everything in one night, whether you can split work into pieces, and whether you explain your decisions.

It's a free advantage: writing clear messages is no harder than writing vague ones, and the difference in impression is considerable.