Topic 09

Reading `status` and `diff`

Core

Two commands answer the two questions you will have most often. git status answers "where am I and what is going on". git diff answers "what exactly did I change".

Between them they are the most-typed commands in Git, and neither changes anything, so there is no such thing as running them too often.

Reading status properly

You have run git status a few times already. Now read it deliberately, because its layout is the three places from earlier in this chapter, printed as a list.

A typical status, mid-session

On branch main

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   index.html

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   style.css

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        notes.txt

The first line names the branch, which will matter enormously from Chapter 6 onward. Then up to three lists: what is in the box, what is on the desk, and what Git has never been asked to look after.

The indented lines in brackets are Git's own suggestions — the command it thinks you probably want next for that list. They are genuinely good, and reading them instead of skipping past them is one of the cheapest ways to learn.

Each status list is one of the three places

Changes to be committed

the staging area — already added, not yet recorded

Changes not staged

the working directory — edited, not yet added

Untracked files

never recorded — invisible to Git until you add them

Seeing the actual change

git status tells you which files changed. git diff tells you what changed inside them.

What you changed but have not staged yet

git diff

Suppose you corrected the meeting time on the home page. The interesting part of the output looks like this:

One line replaced, shown as a removal and an addition

@@ -12,7 +12,7 @@
   <p>The club meets on the first
-  Tuesday of every month at 7pm.</p>
+  Thursday of every month at 7pm.</p>

Lines beginning with - are gone. Lines beginning with + are new. A line that was edited appears as one of each, because Git works in whole lines and has no concept of "this word changed".

The @@ -12,7 +12,7 @@ line is a location marker: which part of the file this section covers. It is information, not a problem, and you can ignore it for months.

The two diffs

Here is the distinction that trips everyone up exactly once. A plain git diff shows only what is not staged. Once you have run git add, that change disappears from git diff and appears in a different command:

What is in the box, waiting to be committed

git diff --staged

So "git diff shows nothing but I definitely changed something" almost always means "I already staged it". The two commands answer different questions: what have I done since I packed the box, and what is in the box.

When to run them

Run git status before every commit — it is how you find out that git add . is about to sweep up a file you never noticed. Run git diff --staged before any commit that matters; it is how you find the debugging line you meant to delete.

Thirty seconds, and it prevents most bad commits. If you build one habit from this chapter, build this one.

A shorter status

When you know the layout by heart, there is a compact form:

The same information, two columns wide

git status -s

It prints one line per file with letters instead of headings: M for modified, A for added, ?? for untracked. Useful once the long form is familiar, and confusing before that — so it is mentioned here and not used again.

Common Confusions

"git diff shows nothing, so nothing changed." It shows nothing when your changes are already staged. git diff --staged is where they went.
"The @@ -12,7 +12,7 @@ line is an error message." It is a location marker saying which lines of the file this chunk covers. It appears in every diff ever produced.
"A changed line should show as 'changed'." Git shows it as a removal plus an addition, because it compares whole lines. This is why reformatting a file produces an enormous and unhelpful diff.
"Running git status too often is a sign I do not know what I am doing." Experienced people run it constantly. It changes nothing, costs nothing, and is the fastest way to answer the question you are actually asking.

Why It Matters

Reading status fluently is what turns Git's messages from intimidating into instructional, because most of them are telling you which of the three lists your file is in.
Checking diff --staged before committing is the cheapest quality habit in this book, and it is the one that catches the leftover debugging line before it becomes permanent.
Knowing the two diffs answer different questions prevents an entire genre of confusion where a change appears to have vanished.

Knowledge Check

You changed a file, staged it, and now git diff prints nothing. What is going on?

The change is staged, so it appears in git diff --staged instead
The change was lost when you staged it, and it needs to be made again
Git only shows differences after a commit has been made, so the diff is empty
The file is untracked, so Git cannot compare it against anything

In a diff, why does one edited line appear as both a removal and an addition?

Because Git compares whole lines and has no idea which words inside them changed
Because the file was saved twice, once before and once after the edit
Because the removal is the staged version and the addition is the unstaged one
Because Git records each change twice for safety and shows both copies

What do the three lists in git status correspond to?

The three places: staged, modified but not staged, and never tracked at all
Three levels of urgency, from changes that must be committed to ones that can wait
Three branches, showing what has changed on each one since the last commit
Three previous commits, showing what each of them changed in the project

Which habit does this topic recommend before every commit that matters?

Run git status, then read git diff --staged before typing the commit
Run git add . first, so nothing you worked on can be left behind
Commit immediately, then check afterwards and fix anything wrong with a second commit
Run git diff on its own, since it shows everything that is about to be recorded

You got correct