Some people keep a diary. Developers don't need one. We have git log, and it tells the story of our year with brutal honesty, one tired sentence at a time.

So as the year wraps up, here's a completely fictional, deeply relatable developer year, told only through commit messages. Any resemblance to your repository is purely coincidental. Probably.

January: new year, new me

feat(auth): add password reset flow with expiring tokens

Tokens expire after 60 minutes and are single-use.
Closes #112.

Look at that. A scope. A body. An issue reference. January-you writes commit messages like they'll be read aloud at an awards ceremony.

February: still going strong

refactor: extract invoice totals into InvoiceCalculator

Still respectable. A little shorter. The body has quietly disappeared, but we don't talk about that.

March: the first crack

fix
fix again
actually fix

Three commits, nine minutes apart. The bug was a missing !. Nobody will ever know which of the three commits contains it.

April: the vague era begins

update
changes
stuff
wip

The commit message equivalent of answering "how was your day?" with "fine". Technically true. Completely useless.

June: the deadline

final
final 2
final FINAL
final-final-use-this-one

Developers mocked designers for naming files logo_final_v3_REAL.psd for years. Then we got Git and did exactly the same thing, but with timestamps.

August: the Friday deploy

small change, should be safe
revert "small change, should be safe"
please

"Should be safe" is the most dangerous phrase in software. "Please" is the only honest commit message ever written.

October: the confession

remove console.log
remove the other console.log
remove debug code I definitely did not push to production

November: the AI era

Refactor and enhance the robust implementation of the
comprehensive user management module to improve
maintainability, scalability and overall code quality

The commit changed one variable name. Generated messages can be genuinely helpful, but only if you read them before you press Enter.

December: acceptance

.

A single full stop. The year has won.

Why any of this matters

It's funny until you're the one running git blame on a strange line of code at 11 p.m. and the only clue is "fix again". Commit messages are the one piece of documentation that's attached to the exact lines it explains, forever. The person who most often reads them is future you, with no memory of why you did it.

Here's what actually makes a commit message useful, without turning it into homework.

Commit messages future you will thank you for

✅ Write the subject as a command. "Add late fee to overdue invoices", not "added" or "adding". A good test: it should complete the sentence "If applied, this commit will…".

✅ Keep the subject short. Around 50 characters, no full stop. It has to fit in git log --oneline, in GitHub's list view and in your terminal.

✅ Explain the why in the body. The diff already shows what changed. The body is for the reason, the trade-off, or the thing you tried that didn't work. Leave a blank line after the subject.

✅ One logical change per commit. If the message needs the word "and", it's often two commits. Small commits are easier to review, revert and bisect.

✅ Squash the noise before merging. "fix", "fix again" and "actually fix" are fine on your branch. Squash or tidy them before they reach main, so the history tells a story instead of a struggle.

✅ Pick a convention as a team. Conventional Commits (feat:, fix:, refactor:) is popular and works well with changelog tools, but the best convention is the one everyone actually follows.

fix(payments): prevent double charge on retried requests

The mobile app retries after a timeout even when the first
request succeeded. Requests now carry an idempotency key,
and duplicates return the original response.

Thirty seconds to write. Saves an hour of archaeology a year from now.

Now be honest: what's the worst commit message in your repository's history? Mine might be a lone full stop.