Writing Commits That Explain the Change

There are four ways to stage, and they are not interchangeable.

$ git add src/auth/redirect.ts    # one file$ git add src/auth/               # a directory and everything under it$ git add .                       # everything under the current directory$ git add -A                      # everything in the repository, wherever you are standing

git add . is the one everybody types and the one worth being slightly suspicious of. It stages every changed and every new file below you, including the ones you forgot about: the scratch file, the screenshot, the .env you created while debugging.

Staging can also be undone freely. Nothing about git add is committal — it is a draft, and changing your mind costs nothing.

$ git restore --staged notes.md    # unstage one file, keeping the edit$ git restore --staged .           # unstage everything, keeping every edit

This is the command that turns staging from a formality into a tool, and most people go years without meeting it.

$ git add -p

Git walks you through your changes one hunk at a time — a hunk being a contiguous run of changed lines — and asks what to do with each. You answer with a single key.

@@ -12,6 +12,9 @@ export async function loadUser(id) {   const res = await fetch(`/api/users/${id}`);+  if (!res.ok) throw new Error("loadUser failed");   return res.json(); }++console.log("DEBUG: got here"); (1/1) Stage this hunk [y,n,q,a,d,s,e,?]?

Press s on that hunk and Git offers the error check and the console.log separately. Stage the first, skip the second, and you have committed the fix without the debug statement — while the debug statement is still in your working tree, still useful, still there when you need it.

A commit message has a shape, and it is not arbitrary. Git, GitHub, and every tool built on top of them treat the first line specially.

Fix the redirect when the next param is empty<-- blank line, and it is load-bearing -->Arriving from /pricing set next="" rather than omitting it,so the guard treated it as a valid destination and senteveryone to the dashboard instead of back to the page theycame from. Checks for a non-empty string rather than a defined one. Fixes #482

The first line is the subject. It shows up in git log --oneline, in the GitHub commits list, in blame annotations, in bisect output, and in the sidebar of every code review tool ever made. Keep it under about fifty characters so it is not truncated.

The blank line is not decoration. Git uses it to tell subject from body; without it the entire message is treated as one long subject and every tool that shows a summary shows the whole paragraph.

The body explains why. The diff already shows what changed — nobody needs a prose translation of it. What the diff cannot show is the reasoning, the alternative you rejected, and the thing that will look wrong to whoever reads it next.

Write "Fix the redirect", not "Fixed the redirect" or "Fixes the redirect" or "Fixing the redirect".

This looks like arbitrary pedantry and it is not. Git itself writes messages in the imperative when it generates them — "Merge branch feature into main", "Revert Add the caching layer". Your messages sit in the same list, and matching the mood makes the log read as one document rather than a pile of styles.

The test that makes it stick: a commit message completes the sentence "If applied, this commit will…". If applied, this commit will fix the redirect. If applied, this commit will fixed the redirect — which is not a sentence.

Everything above is in service of this. A commit that does one thing can be described in one line, reviewed on its own, reverted without collateral damage, and found by bisect. A commit that does four things can do none of those.

The corresponding failure is the opposite extreme — twenty commits called "wip", "wip 2", "fix lint". That is a normal way to work and a bad thing to merge, and there are two good answers to it. Tidy them up before opening the pull request with an interactive rebase, which is a later chapter. Or let GitHub squash them on merge, which is also a later chapter. Both are fine; committing rarely while you work is not the fix.