See the change before you keep it

116. Learning objective

After this lesson, you can read a small text diff and explain:

1. which file changed;
2. what was removed and added;
3. what relevant condition stayed unchanged; and
4. whether the evidence supports keep, investigate, or stop.

Commit and restore mechanics are deferred to the next lesson.

117. Prerequisite check

For the editing exercise, you need:

• a project folder that is already a Git repository; and
• a small, previously tracked text file that is safe to edit.

Run:

git status
git ls-files --error-unmatch path/to/practice-file.txt

Replace the example path with the file you intend to use. If the second command reports an error, the file is not currently tracked and is unsuitable for the main exercise. Use the supplied tracked practice file designated in your course workspace, or another existing tracked documentation or text file that you are allowed to edit harmlessly.

Do not use a binary file, generated file, build output, or important project behavior for this exercise. Do not delete or overwrite pre-existing work to obtain a clean status; record it and choose a different safe file if necessary.

A newly created untracked file can appear in git status, but ordinary git diff does not display its contents. That is why this exercise requires a previously tracked file. If no safe tracked file is available, complete the provided diff-reading examples without making a real edit.

118. Two states, two roles

The checkpoint and the candidate are not the same state.

• Checkpoint: the known working baseline established before the edit. It identifies the state from which the change is attempted.
• Candidate state: the post-edit working state being compared with that checkpoint.

In this lesson, you identify and inspect these states without creating a commit. The next lesson teaches how a commit can record a restore point and how to return to it after a bad change.

119. Checkpoint ritual

Use the canonical ritual:

WORKING STATE → INSPECT → CHECKPOINT → CHANGE → INSPECT → KEEP OR REVERT

The earlier ACT → RESPOND → CHANGE → AGAIN interaction loop remains useful context, but it does not perform checkpoint inspection. Use the checkpoint ritual for the diff-reading decision in this lesson.

120. A diff is evidence, not a verdict

A diff reports textual differences between states. It does not prove that the resulting behavior is correct. Interpret it against:

• the requested change;
• the expected file and region;
• at least one invariant: a condition that should remain unchanged; and
• any available behavior check.

A small diff can still be wrong, and a larger diff is not automatically wrong. The question is whether every relevant mutation can be explained and whether its scope matches the request.

121. How to read a text diff

Suppose the known working checkpoint contains this tracked file:

Pickup settings
heal_amount=10
max_health=100

The request is: “Change heal_amount from 10 to 15. Keep max_health unchanged.” After the edit, git diff displays:

diff --git a/practice/pickup.txt b/practice/pickup.txt
--- a/practice/pickup.txt
+++ b/practice/pickup.txt
@@ -1,3 +1,3 @@
 Pickup settings
-heal_amount=10
+heal_amount=15
 max_health=100

Read the output using textual markers rather than color:

• diff --git ... identifies the compared file paths.
• --- a/practice/pickup.txt identifies the old version of the file. It is a header, not a removed content line.
• +++ b/practice/pickup.txt identifies the new version. It is a header, not an added content line.
• @@ -1,3 +1,3 @@ is the hunk header. It identifies the region shown from the old and new versions.
• A content line beginning with - was present in the checkpoint and removed from the candidate.
• A content line beginning with + was added to the candidate.
• A content line beginning with a space is unchanged context. It helps locate the edit and check nearby invariants.

Do not rely on red and green highlighting. The -, +, header text, and line content carry the meaning even when color is unavailable.

122. Model interpretation

Use three parts to turn the diff into plain language.

1. Identify the affected file

The changed file is practice/pickup.txt.

2. State what was removed and added

The candidate removes heal_amount=10 and adds heal_amount=15.

This is a replacement represented as one removed line and one added line.

3. Compare scope with the request and invariant

The request targeted only heal_amount. The context still shows max_health=100, so the stated invariant is unchanged in this diff. No unrelated file appears.

Decision: keep, provided the available behavior check also agrees. The diff matches the requested textual scope, but the diff alone does not prove runtime behavior.

123. Partially worked example

Request: “Change the practice mode from focus to review. Keep the title unchanged.”

diff --git a/practice/session.txt b/practice/session.txt
--- a/practice/session.txt
+++ b/practice/session.txt
@@ -1,2 +1,2 @@
 title=Diff practice
-mode=focus
+mode=review

Complete the interpretation:

• Affected file: practice/session.txt
• Removed: mode=focus
• Added: mode=review
• Invariant: __________________________________
• Unrelated mutation found: yes / no
• Decision and reason: __________________________________

A complete answer identifies title=Diff practice as unchanged context, reports no unrelated mutation, and supports keep because the candidate matches the requested scope.

124. Read-only inspection sequence

Use these commands to gather evidence:

git status
git diff
git diff --staged

• git status identifies tracked modifications, staged changes, and untracked files.
• git diff shows unstaged changes to tracked files.
• git diff --staged shows staged changes.

These commands are read-only inspections in this workflow. If git status lists an untracked file but git diff shows nothing for it, do not conclude that the file has no content. Ordinary git diff is not displaying that untracked content.

125. Guided practice

Use one previously tracked text file that is safe to edit.

1. Record the working state. Name the file, the current value or line, and one nearby invariant.
2. Inspect before editing. Run git status. Note any pre-existing changes without altering them.
3. Identify the checkpoint. State the known working baseline in one sentence. Example: “Before the edit, mode=focus, the title is unchanged, and the file is tracked.”
4. Define the request. Describe one small replacement and what must remain unchanged.
5. Make the edit. Change only the requested text.
6. Inspect the candidate. Run git status and git diff. If the edit was staged by another workflow, also use git diff --staged.
7. Interpret the diff. Identify the file, removed line, added line, unchanged context, and any unrelated mutation.
8. Decide. Record keep, investigate, or stop. Do not perform restore mechanics in this lesson.

Choose investigate or stop when the diff includes an unexpected file, an unexplained line, a violated invariant, or output you cannot yet interpret.

126. Scored practical interpretation

The request is: “Change heal_amount from 10 to 15. Keep max_health at 100.”

diff --git a/practice/pickup.txt b/practice/pickup.txt
--- a/practice/pickup.txt
+++ b/practice/pickup.txt
@@ -1,3 +1,3 @@
 Pickup settings
-heal_amount=10
+heal_amount=15
-max_health=100
+max_health=120

Submit a text response containing:

1. the affected file;
2. every removed and added content line;
3. the named invariant and whether it held;
4. any unrelated or unexpected mutation; and
5. a keep, investigate, or stop decision with one-sentence justification.

Rubric: 5 points

• 1 point: identifies practice/pickup.txt.
• 1 point: identifies the heal_amount removal and addition.
• 1 point: identifies the max_health removal and addition.
• 1 point: states that the max_health=100 invariant was violated.
• 1 point: chooses investigate or stop and connects the decision to the unexpected maximum-health change.

An image is not required. Copied diff text and a written interpretation are acceptable evidence.

127. Validation record

For your real edit, submit:

• the known working checkpoint before the edit;
• the requested change and one invariant;
• the relevant git status observation;
• the resulting diff as copied text;
• the affected file;
• the removed and added lines;
• the unchanged context used as evidence;
• any unexpected mutation, or an explicit statement that none appeared; and
• a keep, investigate, or stop decision justified by the evidence.

You have met the objective when another developer can read the record, distinguish the checkpoint from the candidate state, reconstruct the small textual change, and understand why the decision follows from the diff.

128. Key takeaways

• The checkpoint is the known working pre-change baseline; the candidate is the post-edit state under inspection.
• - marks removed content, + marks added content, and space-prefixed lines provide unchanged context.
• File headers and hunk headers locate the comparison but are not content edits.
• Untracked files can appear in git status without appearing in ordinary git diff.
• A keep decision requires a diff that matches the request and preserves the stated invariant.

129. Next lesson

Continue to 1.checkpoints L2 — Checkpoint, change, revert, which teaches how to record a restore point and return to it after a bad change.

130. Knowledge check

diff --git a/practice/pickup.txt b/practice/pickup.txt
--- a/practice/pickup.txt
+++ b/practice/pickup.txt
@@ -1,3 +1,3 @@
 Pickup settings
-heal_amount=10
+heal_amount=15
-max_health=100
+max_health=120
```**

A. The affected file is `practice/pickup.txt`.
B. The candidate replaces `heal_amount=10` with `heal_amount=15`.
C. The `max_health=100` invariant was violated because the candidate adds `max_health=120`.
D. Only the requested healing value changed.

<details>
<summary>Show answer and feedback</summary>

*Answer:* The affected file is `practice/pickup.txt`.; The candidate replaces `heal_amount=10` with `heal_amount=15`.; The `max_health=100` invariant was violated because the candidate adds `max_health=120`.

*Why:* The diff affects `practice/pickup.txt` and changes both values. The healing edit matches the request, but the maximum-health edit violates the stated invariant.

</details>