4.2
Commits And History
Why this exists
You can undo now. What you can't yet do is choose where to undo to — and that's the difference between "put it back to this morning" and "put it back to just before we touched the pricing logic."
The gap between those two is entirely determined by how often you commit and what you write in the message. Both are habits, and both take about a week to build.
The idea
A commit is a snapshot plus a note to someone who has forgotten everything. That someone is you, in three weeks.
The snapshot half is automatic. The note is the part you control, and it's what turns a pile of save points into something you can actually navigate.
Compare:
| Message | What it's worth |
|---|---|
update |
Nothing. Fifteen of these and your history is unreadable. |
changes |
Nothing. |
fixed the thing |
Nothing, in a fortnight. |
add pricing table to the client brief |
You can find this in six months |
revert the tone change — client preferred v1 |
This one tells future-you why |
Write what changed and, where it isn't obvious, why. The why is the expensive part to reconstruct and the cheap part to record.
Commit small and often. The instinct is to save when you've finished something big. Do the opposite — commit whenever a piece works. A history of twenty small commits gives you twenty points to return to; four big ones give you four, and every recovery throws away more work than it needed to.
The rough rule: if you'd be annoyed to redo it, commit it.
Three things you'll ask for constantly, in plain English:
| You ask | What you get |
|---|---|
| "What's changed since the last commit?" | Everything currently unsaved |
| "Show me the history" | The list of save points and their messages |
| "Put this file back how it was two commits ago" | Targeted recovery — one file, one point in time |
That third one is the payoff for good messages. Recovering everything to this morning is blunt and costs you the good work too. Recovering one file to the commit before we changed the pricing is surgical — and only possible if the messages tell you which commit that was.
Which produces the habit that actually matters, and it's not a git habit at all:
Commit before you let Claude change several files at once.
This is the single most valuable thing in the level. A multi-file change is exactly where things go sideways in ways you don't spot immediately. A commit beforehand costs five seconds and converts any outcome into a clean undo. Skip it and you're picking through a dozen modified files trying to remember which ones were already right.
Do
Use the real project from 4.1.
- Make a small, genuine change. Ask Claude to commit it with a message describing what changed.
- Do it twice more. Write the messages yourself — don't let Claude pick them. You're building the habit, not it.
- Ask:
show me the history.Read your three messages back. Would they mean anything to you in six weeks? - Rewrite any that wouldn't. Ask Claude how to fix a message if you don't know.
- Now make three good changes and one bad one. Really mangle the bad one.
- Ask:
what's changed since the last commit?Look at the full list. - Recover only the broken file, to a specific earlier commit. Not everything — just that one.
- Confirm your three good changes are still intact.
- Commit the good state.
- Write in
commits.md: your three messages, and one line on which commit you recovered to and how you knew which one.
Step 7 is the lesson and step 10 is the proof. Rolling everything back is the blunt tool everyone learns first. Recovering one file to one point is the tool you'll actually use — and step 10 makes you notice that your own message is what made it findable.
Done when
Never do
Don't let Claude change multiple files without committing first. Five seconds. It converts every bad outcome from an archaeology problem into a one-line undo.
Don't write update as a commit message. A history you can't read is a history you can't use, which makes the commits close to worthless — you kept the snapshots and threw away the index.