Git history your future self can trust

git log is a document. If every message says update or fix stuff, the document is gone and you are left with blame and guesswork. A useful history is a sequence of changes small enough to explain in one sentence.

Say why the change exists#

The diff already shows what changed. The message should say why this change is the whole change. "Fix guide dates that render a day early" beats "update format".

Keep a commit to one reason#

• One bug fix is one commit, even when the fix touches two files.
• Formatting that is unrelated to the fix goes in its own commit, or it does not ride along.
• A commit should build. Do not save a half-migrated type error for the next commit.

git add app/blog/[slug]/page.tsx lib/posts.ts
git commit -m "Render guide dates in UTC so the published day stays stable"

What a reviewer should see#

1. 01

   The subject names the result

   Write it in the imperative, as an instruction to the codebase: render, fix, add, remove.

2. 02

   The body names the constraint

   If you need a body, describe the bug or the rule. Skip the tour of filenames. The diff has those.

3. 03

   The diff matches the subject

   A reviewer should be able to revert the commit without reverting an unrelated cleanup.