Four common styles, judged by a single criterion: how much someone can recover from the message alone, months later, with no other context.
1. Conventional commits
feat(export): add CSV download for analytics
fix(auth): handle expired refresh token on retry
perf(query): batch workspace lookups
Recovers: type, area, change, all machine readable.
Costs: a convention to remember and enforce, and arguments about whether something is a refactor or a fix.
Verdict: best available. The scope in parentheses is the most useful single token in any of these styles, because it groups related commits reliably and vetoes bad groupings.
2. Imperative sentences
Add CSV download to the analytics dashboard
Handle expired refresh tokens on retry
Batch workspace lookups in the dashboard query
Recovers: the change, clearly. Type and area inferable but not reliably.
Costs: nothing. This is what most people do when they are being careful.
Verdict: good. Loses machine readability, keeps everything a human needs. The inference problem is real though: "Fix typo in docs" and "Fix the scheduler race" are structurally identical and worlds apart in importance.
3. Narrative
Finally got the export working, turned out the null check was in the wrong place
Spent way too long on this one, the refresh token expiry was off by a second
Recovers: the change and something about the experience of it.
Costs: long to write, inconsistent, hard to scan a hundred of them.
Verdict: underrated for content, bad for tooling. These are the commits that turn into the best posts, because they contain the "why" that every other style drops. If you are going to write one narrative commit a week, make it the hard one.
4. The default
wip
fix
updates
asdf
more changes
Recovers: that something happened.
Costs: nothing now, everything later.
Verdict: this is fine on a branch you will squash. It is not fine on main, and it is worth knowing that it makes your history useless for archaeology, for changelogs, for blame archaeology and for anything that wants to summarise your work.
The honest position
The style matters less than consistency. A repository that is entirely style 2 is more useful than one that is half style 1 and half style 4, because you can build reliable habits around a consistent history and you cannot around a mixed one.
If you want one rule: write the subject line for someone who will read it in six months without the diff in front of them. That single constraint produces most of the value of any convention.
And if you are squashing anyway, spend the effort on the squash message rather than the fifteen WIP commits behind it. That is where the reading happens.