In the previous lesson we learned to decide precisely what goes into each commit. But there is an earlier question that git status does not answer: what exactly have I changed?

git status tells you which files have changed and which area they are in. It does not tell you which lines. That difference is enormous: committing without having read your own changes is the commonest way of getting a debugging console.log, a test password, a commented-out block of code or a change you thought you had undone into the history.

git diff is the tool that answers the question. In this lesson we will look at its three fundamental forms — and why they produce different results depending on which areas they compare — learn to read the unified diff format line by line (a format that shows up in Git, in code reviews, in patches and across half of computing), and go through the options that make a difficult output readable.

By the end you should have picked up one habit: git diff --staged right before every git commit.

1. The three forms of git diff and what each one compares
2. git diff: working tree against the staging area
3. git diff --staged: staging area against the last commit
4. git diff HEAD: everything that has changed
5. Reading the unified diff format step by step
6. Comparing specific commits
7. Limiting the comparison to files or paths
8. Options that make the output readable
9. git difftool: comparing with a visual tool
10. The habit of reviewing before committing

The whole apparent mystery of git diff dissolves with one idea: it always compares two of the three areas, and the form you use decides which two.

As a table:

Two consequences worth taking on board from the start:

• A bare git diff does not show staged changes. If you stage everything with git add -A and then run git diff, the output will be empty. It is not that you have changed nothing: it is that there is no difference between your disk and the staging area. This is bewilderment number one with git diff.

• git diff HEAD is the sum of the other two. Staged or not, if it differs from the last commit, it shows up.

• None of the three shows untracked files. A new file you have never added has no "previous version" to compare against, so git diff ignores it completely. That is what git status is for.

Back to Ana's repository. She has just tweaked styles.css and has staged nothing yet:

Three seconds and she knows what she did: she softened the border colour and added the pointer cursor. No surprises, no debugging leftovers.

Now she stages the change and repeats:

Precisely: the disk and the staging area agree, so there is nothing to show. To see that change she has to ask for the other comparison.

This is the most important form of all, because it shows literally what you are about to commit:

--cached is an exact and older synonym. --staged was added in Git 1.6 because it read more clearly; use whichever you prefer, though --staged is the plainer of the two.

This is where git diff proves its worth. Ana carries on working and adds one more line to styles.css after staging:

Now the three forms give three different answers:

Three questions, three precise answers. The MM from git status warns you that something odd is going on; git diff tells you exactly what.

It compares your working tree with the last commit, ignoring the staging area. It answers "what have I touched since the last commit?", which is the question you ask yourself coming back from lunch or picking up work in the morning.

There is nothing special about HEAD here: it is simply a reference to a commit, and git diff accepts any of them. These variants are just as valid:

The HEAD~n notation and the other ways of referring to a commit are covered in detail in Viewing Commit History.

The format git diff produces is called unified diff and has been a computing standard since the eighties. You will see it in Git, in GitHub and GitLab code reviews, in email patches and in the output of dozens of tools. Being able to read it is a transferable skill.

Let us dissect a complete output, line by line. Ana has modified app.js:

It signals the start of a file comparison. a/ is the old version and b/ the new one; they are conventional prefixes, not real directories. In a rename you would see different names on each side.

If the diff covers several files, you will see one of these lines per file: it is the separator that tells you where each block begins.

The abbreviated hashes of the old and new blobs, and the file mode (100644 = a normal file). This connects straight back to The Git Data Model: the diff is not an entity stored in Git, it is something Git computes on the fly by comparing two blobs. If the mode changed — say, on making a file executable — you would see old mode and new mode on separate lines.

--- marks the old version and +++ the new one. That is why, in the body of the diff, - means "it was in the old version" and + means "it is in the new one".

Two special cases clear a lot up:

This is the line that takes most getting used to and the one that carries most information. You read it like this:

Applied to the example:

The numbers tell you everything: 8 lines have become 12, so the block has grown by 4. And sure enough, counting the body: 7 context lines, 1 removed and 5 added. That is how you verify any @@ header:

• Old lines = context + removed → 7 + 1 = 8.
• New lines = context + added → 7 + 5 = 12.

The text at the end is not a line of the file: Git extracts it by searching upwards for the last line that looks like a function or section declaration. It helps you get your bearings when the diff is long. It can be tuned per language with .gitattributes, which we cover in File Attributes with .gitattributes.

When the number of lines is 1, it is left out: @@ -12 +12 @@ means "one line on each side".

Every line in the body begins with a character telling you its nature:

Applied to our example:

Two important observations:

1. Git has no notion of "modified lines". A modification is always represented as a removal followed by an addition. That is why the first pair of lines shows up as - and + even though conceptually it is "the same line, changed".
2. The context lines are there for a reason. By default Git shows 3 lines of context on each side of the change, so you can place it. You adjust it with -U<n>:

It means that the file does not end with a line break. That is a POSIX convention many tools take for granted, and its absence produces noisy diffs: if somebody adds the trailing break, every nearby line can show up as changed. Setting your editor to always add the final break avoids that noise.

Before moving on, read this hunk and answer: how many lines did the block have before, and how many does it have now?

Five before, three after: two debugging lines have been removed. This is exactly the kind of find that justifies reviewing the diff before committing.

git diff also compares any two points in the history:

It shows everything that changed between those two commits, aggregated into a single diff. It makes no difference how many commits sit in between: it compares the two end states.

Equivalent and much used forms:

That last one deserves a note: given a single argument, git diff compares that commit with your working tree, not with HEAD. It is the same logic as git diff HEAD.

To inspect a single commit, the idiomatic way is:

which shows the metadata (author, date, message) and the diff. That is the subject of the next lesson.

git diff takes branch names exactly as it takes hashes:

There is also a three-dot notation, git diff main...develop, which compares from the point where the two branches parted ways. Since we work on main throughout this module, we will just note it here: it is developed in module 3.

In a change touching fifteen files, reading the whole diff is unmanageable. You narrow it with -- followed by paths:

The double dash -- separates options from paths. It is optional when there is no ambiguity, so git diff app.js works just as well. It becomes mandatory when a file name could be mistaken for a branch or commit name:

Without the --, Git would try to read main as a reference and, if the branch existed, you would get something completely different from what you asked for. Getting into the habit of putting -- before paths is a good one.

It combines with everything above:

Each line shows the file, the total number of lines affected and a proportional bar of + (additions) and - (deletions). It is the first view worth looking at when facing a large change: it tells you where to look next.

Variants:

--numstat gives additions, deletions and name separated by tabs: ideal for processing in scripts.

--name-status adds a letter per file: M modified, A added, D deleted, R renamed (the number is the similarity percentage: R100 is a rename with no content change).

These options are very practical chained with other commands:

In a text file (documentation, README, HTML content), changing one word makes the whole line show up as removed and added. It is unreadable:

With --word-diff the real change jumps out:

What was removed goes between [- -] and what was added between {+ +}. With colour in the terminal it is clearer still.

Variants:

It is indispensable for reviewing text and very useful in CSS and HTML.

An automatic reformat, a switch of indentation from tabs to spaces or an editor setting can produce a two-hundred-line diff where the real change is two lines. The whitespace family of options solves it:

A word of warning: -w is for reading, not for deciding. If the file is indentation-sensitive (Python, YAML, a Makefile), hiding the spacing changes may hide a real bug from you. Use it to locate the substantive change and then go back to the full diff.

--color-moved is a little-known gem: when you refactor by moving a block from one place to another, it visually distinguishes "this has moved" from "this is new".

For large diffs, or for people who get on better with a two-column view, Git can hand the job over to an external tool:

It accepts exactly the same arguments as git diff.

For Visual Studio Code, which is what Ana uses:

For Meld (cross-platform, free and very clear):

For macOS's opendiff, which suits Bruno:

And one setting almost everybody ends up adding:

Without it, Git asks before opening each file, which is exhausting when the change affects ten of them.

The $LOCAL and $REMOTE variables in that configuration are temporary files Git creates with each version and hands to the tool. All of this is stored in ~/.gitconfig through the mechanism we saw in Configuring Git:

The practical recommendation: use git diff as your default tool — it is faster and always there — and keep difftool for the big changes.

Worth a separate mention: there is also git mergetool, the equivalent for resolving merge conflicts. It is configured along the same lines and we cover it in Resolving Merge Conflicts.

Everything above condenses into a thirty-second routine worth making automatic:

The genuinely valuable step is the second to last. What it usually catches:

• Debugging leftovers: console.log, print, breakpoints.
• Credentials or test URLs.
• Commented-out blocks of code you meant to delete.
• Accidental changes from the editor's autoformatting in files you were not touching.
• Files that slipped in through a hasty git add -A.
• Changes you thought you had made and had not.

If you would rather not run a separate command, the -v option of git commit includes the diff in the message template:

And to leave it switched on permanently:

It is probably the best effort-to-benefit setting in the whole of Git.

• Running git diff after git add and concluding there are no changes. Empty output means "the disk matches the staging area". What you want is git diff --staged.
• Expecting to see new files in git diff. An untracked file has no previous version, so it does not appear. That is what git status is for. If you want to see it, stage it first (git add -N file records it as empty and makes its contents show up in the diff).
• Reading the @@ header backwards. The first number belongs to the old version and the second to the new one. Mixing them up leads to misreading the direction of the change.
• Thinking Git stores diffs. It does not: it stores snapshots and computes the diff when you ask for it, as we saw in the data model. That is why you can compare any two commits, however far apart they are.
• Overusing -w. In indentation-sensitive languages, ignoring whitespace can hide the very bug you are hunting. It is a reading tool, not a final-review one.
• Not using -- before an ambiguous path. If you have a file with the same name as a branch, git diff main will not do what you think.
• Reviewing a 40-file change through the full diff. Start with --stat to see the map, and drop into the detail only where it matters.
• Tip: set aliases for whatever you use most: git config --global alias.d diff and git config --global alias.ds "diff --staged".
• Tip: if the output of git diff seems to "trap" you in the pager, remember that you move through it with the arrow keys or the space bar and leave with q. To turn it off just once, git --no-pager diff.
• Tip: git diff --stat right after git add -A is the quickest way to spot that you have added something you did not mean to.

Set up this scenario and reason out your answer before running each command:

1. What will git status -s show?
2. What will git diff show? How many + lines will it have?
3. What will git diff --staged show?
4. What will git diff HEAD show?
5. If you commit now with no further git add, what will the file in the history contain?
6. Check your answers by running the lot.

Interpret this output and answer the questions:

1. How many files does this change affect, and what happens to each one?
2. In styles.css, how many lines have been removed and how many added? How does the total number of lines in the block change?
3. What exactly does --- /dev/null mean in the second file?
4. What does index 0000000..7a8b9c0 mean?
5. Is there anything in this diff you should not commit? Explain why, and what you would do.
6. Write the command that would show only the per-file summary of this change.

Simulate a file being reindented at the same time as a line of logic changes:

1. Run git diff and count how many lines show up as changed.
2. Use the right option to see only the logic change.
3. Explain why the results of the two commands are so different.
4. What would have been better to do from the outset so that the history stayed readable? Write the correct sequence of commands.
5. Run --word-diff on the same change and comment on whether it adds anything here.

Solution to Exercise 1

1. git status -s:

There is a staged version (change 1) and the disk differs from it (change 2).

2. git diff — the unstaged part. It shows change 2 only:

Two + lines: the blank line and the function. The tasks.push({...}) line shows up as context, not as an addition, because the staging area already holds it that way.

3. git diff --staged — what is going in. Change 1 only:

4. git diff HEAD — the total, both changes together:

5. Committing with no further git add would bring in change 1 only. The file in the history would have the push with the object, but not the countTasks function, which would still be pending in the working tree.

Checking:

Solution to Exercise 2

1. Two files:

• styles.css: modified (there is a --- a/ +++ b/ pair with the same name and mode 100644).
• config.js: a new file, as new file mode 100644 and --- /dev/null show.

2. In styles.css: 3 lines removed (color: #333;, margin-bottom: 1rem; and .hidden { display: none; }) and 1 added (color: #1f2937;).

The count matches the @@ -8,10 +8,8 @@ header: the block goes from 10 to 8 lines, losing 2 (−3 +1 = −2). And you can verify it by counting the hunk's lines by hand:

• Old version = context lines + - lines → 7 context + 3 removed = 10.
• New version = context lines + + lines → 7 context + 1 added = 8.

This checking exercise is the best way to make sure you have understood the @@ header: the two numbers must always tally with what you see in the body.

3. --- /dev/null says that the old version of the file does not exist: it is a new file. /dev/null is the "null device" of Unix systems, and here it stands for "nothing at all". The mirror case, +++ /dev/null, would mean a deletion.

4. index 0000000..7a8b9c0 are the hashes of the old and new blobs. The left-hand one is all zeros because there is no old blob: consistent with the file being new.

5. Yes, there is a problem: DEBUG_KEY = 'test-1234' in config.js. Test key or not, it is a secret in the code, and committing it leaves it permanently in the history for anybody who clones the repository. Harmless as it may be today, it sets a bad precedent and it is exactly the mechanism by which real keys end up leaking.

What I would do:

If config.js should not be versioned at all:

6. The per-file summary:

Solution to Exercise 3

1. The full diff:

Fourteen lines show up as changed (7 removed and 7 added), when the real change in behaviour is just one.

2. Seeing the logic alone:

Now there is only one -/+ pair: the condition. The indentation of the other lines is ignored, so the real change stands on its own.

3. Why the difference is so large. Git compares whole lines, character by character. Swapping four spaces for two at the start of a line makes it, as far as Git is concerned, a different line: the old one is removed and the new one added. Since the reformat touches all seven lines of the function body, all seven show up as changed and the logic change is lost among them. -w tells Git to normalise whitespace before comparing, leaving only the real difference.

4. The right approach from the outset: two separate commits. Mixing reformatting with functional changes is a well-known bad practice, because it makes the change impossible to review and ruins git blame for the whole block.

The diff of the second commit is two lines and can be reviewed in five seconds. On top of that, if the logic change has to be undone tomorrow, it comes out without dragging the reformat with it.

If the two changes are already mixed on disk, git add -p with the e option lets you separate them, though in this particular case — where each line contains both changes at once — redoing the work in two steps would be more practical.

5. With --word-diff:

It helps a good deal: comparing by words rather than by lines all but removes the noise from the reindentation, and the change to the condition is pinpointed surgically. In text changes and in cases like this one, --word-diff and -w complement each other well:

You can now read changes before they enter the project's story. To recap:

• git diff always compares two areas, and the form you use decides which: git diff (disk ↔ staging), git diff --staged (staging ↔ HEAD) and git diff HEAD (disk ↔ HEAD, that is, the total).
• Empty output from git diff does not mean "I have changed nothing": nearly always it means you have already staged everything.
• No git diff shows untracked files. That is what git status is for.
• The unified diff format has a fixed structure: a diff --git header, blob hashes, ---/+++ markers, @@ -a,b +c,d @@ hunk headers with their context, and context, removed (-) and added (+) lines. Git does not represent "modified lines": a modification is a removal plus an addition.
• Any two commits can be compared (git diff <sha1> <sha2>) and narrowed by path with -- <path>, using -- whenever the name could be ambiguous.
• The options change readability radically: --stat for the overall map, --name-only/--name-status for the list, --word-diff for text and -w for separating the real change from spacing noise.
• git difftool hands over to a visual tool and takes the same arguments; it pays off on large changes.
• The habit that matters: git diff --staged before every git commit, or simply commit.verbose = true.

With git status you know where you are, with git diff you know what you have changed, and with git add/git commit you decide what gets recorded. One piece of the basic cycle is missing: looking backwards.

A history is only worth as much as your ability to query it. After two hundred commits, how do you find when a function was introduced? Who touched styles.css last week? In which commit did that line you swear you wrote disappear?

In the next lesson, Viewing Commit History, we will look at git log with all its formats and filters, custom formats with --pretty, the "pickaxe" search that finds when a particular piece of text appeared or vanished, git show for inspecting a commit, and the various ways of referring to a commit — HEAD, HEAD~3, HEAD^ — that we have been using in passing and that are worth understanding properly.