131. Lesson identity
132. Learning objective
After this lesson, you can create a Git checkpoint, make a throwaway change, recover the tracked file to that checkpoint, and verify that the working-tree state has been restored without rewriting commit history.
133. Why this matters
A checkpoint is useful only when it gives you a dependable place to return to. In an AI-assisted project, small edits can accumulate quickly, and a plausible change can still damage an unrelated file. This safety loop lets you test an idea without treating every experiment as permanent. It also gives you evidence that the repository is ready for the next deliberate change.
134. Prior knowledge
You should have completed See the change before you keep it in this module. You should be able to inspect git status and read a diff before accepting a change. You also need a local project repository with Git available. If the working tree contains changes you do not recognize, stop and identify them before continuing.
135. Core concept
A commit is a named checkpoint. For an uncommitted change in a tracked file, git restore --source=HEAD -- path/to/file replaces that file in the working tree with the version at the current commit (HEAD); it does not rewrite commit history. The shorter git restore -- path/to/file restores the file from the index, which normally matches HEAD immediately after a clean checkpoint commit, but should not be described as inherently restoring the last committed state. The sequence matters:
- Inspect the current state.
- Commit a known-good checkpoint.
- Make one disposable change.
- Inspect the diff.
- Restore only the disposable change.
- Inspect again and confirm the state.
git restore is appropriate here because the goal is to discard an uncommitted working-tree change. It is not the same operation as rewriting commit history with git reset or deleting a commit from a shared branch.
136. Mental model
The checkpoint ritual
The primary model for this lesson is:
WORKING STATE → INSPECT → CHECKPOINT → CHANGE → INSPECT → KEEP OR REVERT
| Step | Question | Evidence |
|---|---|---|
| WORKING STATE | What state exists before I evaluate the experiment? | git status and a readable diff |
| INSPECT | What does the current repository state show? | Status and relevant diff |
| CHECKPOINT | What known-good state am I protecting? | A precise commit and its commit ID |
| CHANGE | What single disposable experiment am I making? | A focused diff in the intended file |
| INSPECT | Does the new evidence match the intended scope? | A second diff and the relevant check |
| KEEP OR REVERT | Should I preserve the change or return to the checkpoint? | An explicit decision supported by evidence |
The Stage 1 interaction loop remains supporting context: ACT → RESPOND → CHANGE → AGAIN. It describes an action, its result, a change, and another attempt. It does not replace the checkpoint ritual. Use the ritual to protect a known-good state, inspect the experiment, and decide whether to keep or revert it.
137. Concrete example
Suppose the project is in a known-good state and you want to test a temporary label change in a tracked documentation or configuration file. You can protect the starting point, edit only that file, inspect the diff, and then restore it:
git status
git add path/to/tracked-file
git commit -m "Checkpoint before disposable label test"
# Make one small, temporary edit to path/to/tracked-file.
git diff -- path/to/tracked-file
git restore --source=HEAD -- path/to/tracked-file
git status
git diff -- path/to/tracked-file
After the restore, the temporary edit should no longer appear in the diff. The checkpoint commit remains in the history. Replace the example path with a tracked file you are permitted to edit; do not use a file containing unrelated work.
138. Git workflow
Work from the repository root and keep the scope narrow.
- Run
git status --short. - If the output lists changes you did not create or cannot explain, do not commit them. Ask for clarification or return to a known state first.
- Inspect the relevant diff with
git difforgit diff -- path/to/file. - Stage only the known-good files for this checkpoint. Avoid
git add .when the working tree may contain unrelated work. - Create the checkpoint with a precise message, such as
Checkpoint before disposable label test. - Record the short commit ID with
git log -1 --oneline. - Make exactly one harmless, temporary change in one tracked file.
- Run a path-scoped diff and confirm that the diff contains only that experiment.
- Restore the file with
git restore -- path/to/file. - Run
git status --shortand inspect the path-scoped diff again.
Do not use git clean, git reset --hard, or a broad restore command for this exercise. Those commands can remove more than the intended throwaway change. If your experiment creates an untracked file, remove it manually only if you are certain it belongs to the exercise, or stop and inspect it rather than assuming that git restore will remove it.
139. Common mistake
The common mistake is committing immediately after making the throwaway change. That turns the experiment into part of the checkpoint and leaves git restore with nothing to remove. Another mistake is treating a clean working tree as proof that the game behavior is correct. A clean status proves only that Git sees no uncommitted tracked changes; it does not replace running the relevant check or inspecting the restored file.
140. Guided practice
Complete this sequence in the project repository:
- ACT: Run
git status --shortand inspect any relevant diff. Write down the file you will use and the state you intend to protect. If the tree is not clearly known-good, stop rather than committing uncertainty. - RESPOND: Stage only the known-good files and create a checkpoint commit. Confirm the commit with
git log -1 --oneline. - CHANGE: In one tracked file, make a small, reversible edit that is easy to identify. Do not modify gameplay logic or combine multiple experiments. Inspect the diff and decide whether it contains exactly the change you intended.
- AGAIN: Recover the file to the checkpoint with
git restore --source=HEAD -- path/to/file. Inspect the file, rungit diff -- path/to/file, and rungit status --short. This restores the working-tree copy from the current checkpoint; it does not remove or rewrite the checkpoint commit. - Decision point: If the status is not what you expected, do not run a stronger command automatically. Determine whether the remaining state is an untracked file, an unrelated change, or an incorrectly scoped restore. Preserve unrelated work and correct only the exercise change.
Repeat the exercise once with a different harmless tracked file only if the first pass was clear. The goal is reliable judgment about scope, not speed.
141. Validation / evidence
You have completed the practice when you can point to all of the following:
- A checkpoint commit ID and a message that describes the protected state.
- A before-and-after diff showing the temporary change existed before restore and disappeared afterward.
- A final
git status --shortresult that matches your expectation. - The restored file matching the checkpoint state.
- A written note identifying why a path-scoped restore was safer than a broad destructive command.
If the project requires a separate build or run check, perform it after restoration and record the result. Git evidence confirms repository state; it does not by itself validate game behavior.
142. Key takeaways
- A commit is a deliberate return point, not merely a record of activity.
- Inspect the working tree before committing and inspect the diff after every experiment.
- Use a path-scoped
git restorefor a disposable uncommitted change. - A successful command is not enough; verify the restored state with status, diff, and the file itself.
- Protect unrelated work instead of using a broad command to make the status look clean.
143. Knowledge check
Complete the knowledge check for this lesson. Use the explanations to compare the command choice and evidence standard with your own practice.
144. Next lesson
Continue to 1.ai-partner — Directing the AI Partner.
145. Git on Pulse Loop (fix-git-regression later)
In your Pulse Loop learner copy: git status, checkpoint commit, one disposable change, inspect the diff, path-scoped restore, verify status. Evidence is commit id, diff, and restored file. Stage 3 lab academy-fixtures/labs/git-regression (node run.mjs) uses a temp repo — not this course repository.
146. Knowledge check
Answer these items for yourself before reading the answers.
What is the purpose of creating the checkpoint before making the throwaway change?
Show answer and feedback
Answer: To create a known return point for the experiment
Why: The checkpoint records the known-good state so the disposable experiment has a deliberate point of comparison and return.
Which command is the focused choice for discarding an uncommitted change in one tracked file?
Show answer and feedback
Answer: git restore -- path/to/file
Why: A path-scoped git restore discards the uncommitted working-tree change in the specified tracked file without broadly changing other files or commit history.
What should you do if the working tree contains changes you cannot explain before creating a checkpoint?
Show answer and feedback
Answer: Stop and identify or clarify the changes first
Why: An unexplained change may belong to unrelated work. Committing or deleting it without understanding its scope can destroy evidence or someone else's work.
What does a clean final git status prove after the restore?
Show answer and feedback
Answer: That Git detects no remaining uncommitted tracked changes in the inspected scope
Why: A clean status is repository-state evidence, not proof of correct game behavior, absence of mistakes in the commit, or safe deletion of untracked files.