git commit -m "Added more bugs to fix later"

Most developers have written some version of this message. Usually at six in the evening, usually after a long day, usually on a commit that touches fourteen files. It's a joke, but it might also be the most honest commit message ever written. Every commit adds bugs. We just don't know which ones yet.

You can't stop shipping bugs. What you can do is make them cheap to find, and a lot of that comes down to the history you leave behind.

Your history is a debugging tool

When something breaks, the history is one of the first places to look. git log shows what changed. git blame shows which commit last touched a line. And that commit's message is supposed to explain why.

That's where most messages fall short. "fix", "wip", "updates" and "final final v2" tell future you nothing. A good message turns the history into documentation that can't go out of date, because it's attached to the exact lines it describes.

Small commits make bugs findable

A commit that does one thing is easy to review, easy to revert and easy to understand when it turns up in git blame. A commit called "misc changes" that touches forty files is none of those.

Small commits also make one of git's most underrated commands far more useful. git bisect runs a binary search through your history to find the commit that introduced a bug:

bashgit bisect start
git bisect bad              # the current commit has the bug
git bisect good v2.3.0      # this release didn't
git bisect run npm test     # let git test each step for you
git bisect reset            # back to where you started

With a thousand commits between good and bad, bisect needs about ten steps to find the culprit. If that culprit is a small, well-described commit, you often know what's wrong the moment you see it. If it's "Added more bugs to fix later" across forty files, you're back to square one.

What a useful message says

The format I use is type(scope): summary, with a body underneath when the change needs explaining:

fix(payments): stop double charge when a payment is retried

The payment provider retries webhooks that time out, and we created
a new charge on every retry. Store the provider's event ID and skip
events we have already processed.

Each part answers a question before anyone has to open the diff:

• Type: what kind of change it is, such as feat, fix, refactor, test, docs or chore.
• Scope: which part of the code it touches, like payments, auth or settings.
• Summary: what changed, in a few words. Keep the whole line under about 72 characters so it fits in one-line logs.
• Body: why the change was needed. The diff already shows how, so use the body for the reason, the edge case, the trade-off or the approach you tried that didn't work.

This is the Conventional Commits format, and a log written in it reads like a table of contents:

feat(settings): add dark mode
fix(payments): stop double charge on retry
refactor(payments): split checkout into smaller services
chore(deps): upgrade dependencies

Tools can also read it to generate changelogs and version numbers automatically. The exact list of types matters less than everyone on the team using the same one.

By these rules, the title of this post should have been feat(bugs): add more to fix later.

The same idea extends to branch names. A branch name only matters while people are working on it, because once it's merged, the commits and the pull request carry the record. But on a team with hundreds of branches, a clear name tells everyone what's going on without opening anything. I name branches the same way as commits, with the type, a slash and what the work is about: refactor/payment-system, fix/double-charge-on-retry or feat/dark-mode.

Write for whoever is debugging at 2 a.m.

Sooner or later, someone will open your commit while something is on fire. Often that someone is you, six months later, with no memory of writing it. Give them a fighting chance: one change per commit, a first line that says what changed and where, and a body that says why.

The bugs are coming either way. A good commit message is the note you leave for whoever has to fix them.