In the previous section, you learned how git diff can show you the differences between various states in your repository. By default, running git diff without any extra arguments compares your current working directory files against what's in your staging area (also known as the index). This is useful, but sometimes you need more specific comparisons, particularly differentiating between changes you've staged and changes you haven't staged yet. Understanding this distinction helps you craft precise commits.

Let's clarify the comparisons:

Unstaged Changes: These are modifications you've made to tracked files in your working directory after the last time you ran git add on them (or since the last commit if you haven't staged anything).
Staged Changes: These are modifications you have explicitly marked for inclusion in the next commit using git add. They reside in the staging area, waiting to be permanently recorded.

Viewing Unstaged Changes

To see the changes in your working directory that you have not yet staged, you simply run:

git diff

This command compares the files in your working directory directly against the files in the staging area. If you haven't staged any changes since your last commit, this command effectively shows differences between your working directory and the last commit (HEAD). However, as soon as you stage some changes using git add, git diff will only show the differences introduced after that staging operation.

Consider this sequence:

You have a file, report.md, tracked by Git and committed.
You edit report.md, adding a new paragraph.
Running git status shows report.md as modified but not staged.

Running git diff shows the lines you just added in report.md.

diff --git a/report.md b/report.md
index e69de29..abcdef0 100644
--- a/report.md
+++ b/report.md
@@ -0,0 +1,3 @@
+This is the first line.
+This is the newly added paragraph.
+This is the final line.

(Output simplified for clarity)

You stage the file: git add report.md.
Now, running git diff again shows no output, because the version of report.md in your working directory now exactly matches the version in the staging area.

Viewing Staged Changes

So, how do you review the changes you've just staged, the ones poised for the next commit? You need to compare the staging area against the last commit (HEAD). For this, Git provides the --staged option (or its older alias, --cached):

git diff --staged

git diff --cached

Both commands do the same thing: they display the differences between the snapshot recorded in the staging area and the snapshot represented by the last commit (HEAD). This is extremely useful for a final review before running git commit.

Let's continue the previous example:

You have just run git add report.md. The new paragraph is now staged.
Running git status shows report.md as "Changes to be committed".
Running git diff --staged will now show the difference between the staged report.md (with the new paragraph) and the version in the last commit (without it). The output would look similar to the git diff output we saw before staging the file.
```
diff --git a/report.md b/report.md
index e69de29..abcdef0 100644
--- a/report.md
+++ b/report.md
@@ -0,0 +1,3 @@
+This is the first line.
+This is the newly added paragraph.
+This is the final line.
```
(Output simplified for clarity)
Now, imagine you edit report.md again, perhaps fixing a typo in the paragraph you just added, but you don't run git add afterwards.
Running git diff (with no options) will show only the latest change (the typo fix) because that's the difference between your working directory and the staging area.
Running git diff --staged will still show the original addition of the paragraph, as that is what's currently in the staging area compared to the last commit.

This separation allows you to precisely control and review what goes into your next commit.

This diagram illustrates the comparisons performed by git diff and git diff --staged. git diff compares the Working Directory to the Staging Area, showing unstaged changes. git diff --staged compares the Staging Area to the Last Commit (HEAD), showing staged changes ready for commit.

In summary:

Use git diff to see changes you haven't staged yet.
Use git diff --staged to review changes you have staged and are about to commit.

Mastering these two variations of git diff gives you finer control over inspecting your work before committing, helping you maintain a clean and understandable project history.