Lesson 41.1 gave the project a memory. This lesson teaches how to write useful memory instead of a blurry pile of snapshots. A repository that records "AI changes, final final, fix stuff" is barely better than no history at all.

Meet the terms in the order you meet them

• The working tree is the current files in the project folder, including changes not yet saved as a checkpoint.
• A changed file is a tracked file you modified. An untracked file is a new file Git has never recorded.
• The staging area is the selection step: which changed files belong in this checkpoint. It is not a ritual. It is a decision — this commit contains *these* files, not everything that happens to be dirty.
• A commit is a named, intentional checkpoint of the selected changes in Git history.
• A diff is a readable comparison showing added, removed, and changed lines between versions.

That order is the workflow: you edit the working tree, you inspect what changed, you select what belongs together, you record it with a message, and the diff is the proof of what you recorded.

For the deeper mechanics behind any of these, the Pro Git book is the durable reference.

The commit loop

Tape this to the wall:

inspect current state
  → make one coherent change
  → inspect the diff
  → run the relevant check
  → select the intended files
  → commit with a useful message
  → record what the checkpoint proves

Notice what comes first and last. You inspect *before* you change, so you know what was already dirty. And you record what the checkpoint proves, so a future reader — human or AI — knows whether this commit was verified or merely saved.

The loop is small on purpose. It is the plan → change → verify → checkpoint rhythm from Part IX, now written into permanent history.

One coherent change

A commit should be a readable historical sentence, not a dump truck.

Good: "show publication date beside citations and handle a missing date." One idea, a few files, one reason.

Bad: "fix citation dates, switch CSS framework, update dependencies, and rewrite login." Four ideas, dozens of files, no single reason. When the login rewrite breaks next month, nobody can revert it without also reverting the citation fix.

The test is simple: can you describe the commit in one imperative sentence without the word "and"? If you need three sentences, you probably need three commits — or a smaller task.

The research dashboard makes this concrete. The source-date feature arrives as separate checkpoints: one commit exposes the date in the data mapping with a test, a later commit renders it beside each citation. If rendering breaks, history shows exactly which checkpoint to inspect.

The neighborhood-events finder is the same. "Show event venue on the card" is one commit. "Switch the data source and redesign the card" is not.

Message anatomy

A useful commit message has a short imperative summary — a command, not a diary entry:

• feat: display source publication dates in research brief
• fix: preserve export when a source date is absent

Start with a type (feat, fix, docs, test, refactor), then say what the change does. Imperative mood: "display," "preserve," "add" — as if ordering the codebase.

Add a "why" only when the reason is not obvious from the summary. "Preserve export when a date is absent" earns a body line explaining that the provider returns null for some sources and the old code dropped the whole citation. "Fix typo in README" does not.

Never write "fix stuff," "updates," "final," or "final final." Those are confessions that you did not decide what the checkpoint contains.

Commit-message bank (copy, don't invent)

When a message feels hard to write, pick the closest shape and fill the blanks. All use imperative mood:

feat: <visible behavior> [e.g. feat: display source publication dates in research brief]
fix: <broken behavior> when <condition> [e.g. fix: preserve export when a source date is absent]
docs: <what the reader can now do> [e.g. docs: explain how to run the preview]
test: cover <case> for <feature> [e.g. test: cover missing-date state for source card]
refactor: <what changed internally> with no behavior change [e.g. refactor: extract date formatter with no behavior change]
chore: <maintenance task> [e.g. chore: ignore local preview output in git]
revert: <what is undone and why> [e.g. revert: hide citation-date change after null-date regression]

Rules: one type prefix, one outcome, no period at the end of the summary. Add a body (2–4 lines: why, what was considered, what check proves it) whenever the reason is not obvious from the summary — especially for fix: and revert:.

Read the diff like a reviewer

A diff shows added lines (usually marked +) and removed lines (usually marked −), with a few unchanged lines for context. Before every commit, read it and ask:

1. Does it touch only the expected files? 2. Does it alter a dependency, secret, configuration, database schema, or access rule? 3. Does it include generated artifacts, lockfile churn, or unrelated formatting noise? 4. Does the change actually meet the acceptance check for this task?

Question 2 is the one AI work fails most often. An agent asked to "show the date" may also bump a dependency, touch an env example, or reformat ten files. The diff catches what the chat summary hides.

Question 3 deserves a habit: generated files and bulk reformats belong in their own commits or not at all. Mixed into a feature commit, they make review impossible.

A commit is not a deployment, a review, or a proof

This distinction saves careers:

• A commit is a local, named checkpoint. Nothing else has approved it.
• A deployment puts some version where users or a preview can run it.
• A review is another intelligence checking the work.
• A proof is evidence — tests, a browser walkthrough, an API response — that the change does what it claims.

Committing "fix: handle missing date" does not mean the fix works, was reviewed, or is live. It means the change is recorded under a name you can find, discuss, and undo. Lessons 41.3 and 41.4 add the review and recovery layers.

Directing an AI through the loop

Require the agent to report before it commits:

• Which files changed and why each belongs in this checkpoint.
• The diff, or at least a file-by-file summary of it.
• Which check it ran and the actual output — not "tests pass," but the command and result.

And forbid the one dangerous shortcut: never let an agent add every modified file blindly. The command that stages everything (git add -A / git add .) is fine only after a human has read the diff and agreed every changed file belongs in this one checkpoint. Blind add-all is how secrets, scratch files, and unrelated edits enter permanent history.

A good agent brief sounds like this: "Show me git status and the diff. Tell me which files belong to the citation-date change and which do not. Run the citation test and paste the output. Do not commit until I confirm the file list."

Exercise: one documentation-only commit

On a learning project, make a single documentation change — for example, add a "How to run the preview" section to the README. Then:

1. Run git status and read the diff (git diff before staging, git diff --staged after). 2. Confirm the diff contains only that documentation change. 3. Commit with an imperative message such as docs: explain how to run the preview. 4. Compare before and after with the history view (git log --oneline -5 and git show HEAD --stat).

Check your understanding

• Why is the staging area a decision rather than a ritual?
• Rewrite "fixed dashboard stuff" as a commit message that would help you six months from now.
• An agent ran the tests and says "all good." What two things do you ask for before it commits?

Finish line

You are done when you have one commit whose diff, message, and validation you can explain in plain English: what changed, why, and what check proves it.

Verify: open the commit in the history view. Confirm the message is imperative and specific, the diff touches only intended files, and you can name the check and its result. If you cannot, the checkpoint is a rumor — amend the message or split the change before moving on.

Common failure mode: one giant "AI changes" commit with forty files and no message. Recovery: if the work is still uncommitted, split unrelated changes into separate selections before committing. If it is already committed, record the problem honestly, keep the history readable from here, and return to smaller tasks next time.