Inspect Changes Before You Commit

Core path: 30 minutes

A commit is a permanent checkpoint in your project history. How do you know what you are actually about to record?

You inspect the change.

That sounds obvious. It is also one of the first habits people abandon when they are moving fast.

git diff shows content change, not intent

Suppose you changed:

- if score >= 900:
+ if score >= 1000:

Git can show that the line changed.

Git does not know whether:

1000 is the new requirement
you typed an extra zero by accident
the test data changed too
the threshold should have been 950

The diff is evidence about what changed.

You still need the requirement or bug report to decide whether the change is correct.

Read a unified diff deliberately

A diff may look like:

@@ -12,5 +12,5 @@
-LOW_BATTERY = 20
+LOW_BATTERY = 25

Useful reading rules:

- line → content removed from the compared state
+ line → content added in the new state
context lines → nearby unchanged content
@@ ... @@ → location/range information

The + does not mean "good" and - does not mean "bad."

They describe the transformation.

One intended change can hide an unrelated edit

Imagine the task is:

Change the low-battery threshold from 20 to 25.

But git diff shows:

- if battery <= 20:
+ if battery <= 25:
     print("LOW BATTERY")

-print("debug value:", battery)

The threshold change clearly matches the task.

The removed debug line might also be fine. Or it might be unrelated cleanup you forgot you performed.

Before staging, decide:

Do both edits belong to the same checkpoint?

That question becomes extremely important when debugging history later. A focused commit is easier to inspect, understand, revert, and review.

Staging is a selection boundary

A disciplined workflow:

edit
↓
run/test relevant behavior
↓
git diff
↓
choose what belongs in this checkpoint
↓
git add intended paths/content
↓
git status
↓
inspect staged diff
↓
commit

Blindly typing:

git add .

can be convenient when all current changes truly belong together.

It becomes dangerous when you have forgotten what else is dirty.

The command is not the problem. Skipping the inspection is.

Staged and unstaged content can exist in the same file

This is subtle and worth seeing once.

1. edit main.py;
2. stage it:

git add main.py

3. edit main.py again;
4. run:

git status

Git may show main.py in both staged and unstaged categories.

Why?

The staging area contains the version you staged earlier.

The working tree contains a newer edit.

So the filename alone is not the full state.

Use:

git diff

for unstaged differences and:

git diff --staged

for the content currently prepared for the next commit.

The staged diff is the commit preview

Before committing, run:

git diff --staged

Then ask:

• Does every changed line belong to this checkpoint?
• Did I accidentally stage generated data or a secret?
• Did a test change in a way that weakens the requirement?
• Did formatting noise bury the functional change?
• Does the commit message I plan to use actually describe this diff?

If you cannot summarize the staged diff in one or two sentences, the checkpoint may be too broad or you may not understand the change yet.

History gives you checkpoints to compare

git log --oneline

might show:

a8c7f22 Add player search
d31bd19 Save roster to JSON
0cf29ea Create roster application

The shortened hashes identify specific commits.

You can inspect one:

git show a8c7f22

or compare states:

git diff d31bd19 a8c7f22

Git does not merely let you go backward. It lets you ask how one recorded state differs from another.

That turns history into debugging evidence.

A commit message is a claim about the diff

Message:

Fix empty roster crash

If the commit also redesigns menus, renames modules, changes five tests, and adds an API dependency, the message is no longer a useful summary.

The commit is allowed to contain those changes technically.

The history becomes harder for humans to trust.

This is why good Git practice is not just command memorization. It is information design.

Review a suspicious patch

Task:

Make score search case-insensitive.

Diff:

- if player["name"] == query:
+ if player["name"].lower() == query.lower():
     return player

-LOW_BATTERY = 20
+LOW_BATTERY = 25

The first hunk matches the requested search change.

The battery threshold does not.

Before staging, separate or revert the unrelated edit unless the scope has been deliberately expanded.

Now imagine an AI coding agent produced this patch and claimed:

Implemented case-insensitive player search.

The summary is not lying about the first hunk. It simply does not mention the second.

This is why Weeks 15–17 will return to git diff constantly.

Verification comes before history, not from history

A clean focused diff can still contain a bug.

So the sequence is not:

looks small → commit → assume correct

It is:

requirement
↓
change
↓
relevant runtime/test evidence
↓
diff review
↓
stage review
↓
commit

Git records the state you chose. It does not validate the state for you.

Success check

Before your next commit, be able to say:

I expected these files to change:

The unstaged diff shows:

The staged diff shows:

I ran this verification:

This commit message describes the checkpoint because:

If you cannot answer those questions, do not rush to record the checkpoint just to make git status clean.