Git diff Command: How to Use It

The git diff command shows the changes between two versions of files in a Git repository—what was added, removed, or modified, line by line. You run it in your terminal within a Git repository, and it outputs a text-based patch that highlights the exact differences. It is one of the most frequently used Git commands because it lets you review changes before committing, compare branches, and inspect what has been staged.

What Exactly Does git diff Show?

At its core, git diff compares two snapshots of your project. A snapshot can be a commit, a branch, a tag, or your current working directory. The command shows the differences as a patch—a standardized format that lists which lines were removed (marked with a minus sign) and which were added (marked with a plus sign).

For example, if you change a line in a file from Hello to Hello, world!, git diff will show:

diff --git a/hello.txt b/hello.txt
index 980a0d5..b1a4f2c 100644
--- a/hello.txt
+++ b/hello.txt
@@ -1 +1 @@
-Hello
+Hello, world!

The --- line refers to the original file, and the +++ line refers to the new version. The @@ line indicates the line numbers affected. This format is the same used by the patch tool, so you can apply a diff to another copy of the project.

How Git Diff Works Under the Hood

Git stores content as snapshots, not as a list of changes. When you run git diff, Git compares two snapshots by looking at the blob (file content) hashes. If the hashes differ, Git runs a line-by-line comparison algorithm (typically Myers diff) to find the minimal set of insertions and deletions that transforms one version into the other.

The command does not modify anything—it is read-only. It only reads the repository and the working directory. That means you can run it as often as you like without worrying about breaking anything.

Git has three main “trees” of state:

Working directory: the files you see and edit.
Staging area (index): the snapshot you have marked for your next commit.
HEAD: the last commit on the current branch.

Depending on which combinations you compare, git diff shows different things:

git diff (no arguments) compares working directory to the staging area.
git diff --staged (or --cached) compares staging area to HEAD (what will be committed).
git diff HEAD compares working directory to HEAD (all changes, staged and unstaged).

Common Use Cases and Examples

Here are the most frequent ways developers use git diff:

Review unstaged changes: git diff shows what you have modified but not yet staged.
Review staged changes: git diff --staged shows what you have added to the staging area and will be included in the next commit.
Compare two commits: git diff commit1 commit2 shows differences between two specific commits.
Compare two branches: git diff branch1 branch2 shows differences between the tips of two branches.
Check changes in a specific file: git diff -- path/to/file limits the output to that file.
See a summary: git diff --stat shows a summary of which files changed and how many lines were added/removed.

For example, to see what changed in the last three commits, you could run:

git diff HEAD~3 HEAD

This compares the state three commits ago with the current HEAD.

How to Read the Diff Output

The output can be intimidating at first, but it follows a consistent structure. Here is a breakdown of each part:

Header lines: diff --git a/file b/file tells you which file is being compared. The index line shows the blob hashes before and after.
File markers: --- and +++ indicate the old and new file paths. A /dev/null means the file was added or deleted.
Hunk headers: @@ -start,count +start,count @@ show the line numbers in the old and new files. For example, @@ -10,5 +10,6 @@ means the old file had 5 lines starting at line 10, and the new file has 6 lines starting at line 10.
Lines: Lines starting with - are removed, + are added, and a space means unchanged context.

Many developers use a pager like less to scroll through large diffs. You can press q to quit, space to page down, and / to search.

Common Mistakes and How to Avoid Them

One frequent mistake is expecting git diff to show staged changes by default. It does not—you must use --staged. If you run git diff after staging a file, you will see nothing for that file because the working directory matches the staging area.

Another issue is comparing the wrong things. For example, git diff branch1 branch2 compares the tips of the branches, not the common ancestor. If you want to see what changes are unique to branch2 relative to branch1, you might want git diff branch1...branch2 (three dots), which compares the merge base of the two branches to branch2. This is a common point of confusion.

Also, be aware that git diff does not show untracked files. If you create a new file and run git diff, nothing appears because Git does not track it yet. Use git status to see untracked files.

Finally, line-ending differences (Windows CRLF vs Unix LF) can cause spurious diffs. You can configure Git to handle line endings automatically with core.autocrlf or a .gitattributes file.

Alternatives and Related Tools

While git diff is the command-line standard, there are alternatives:

Visual diff tools: Many graphical Git clients (like GitKraken, SourceTree, or the built-in tools in VS Code) show diffs side-by-side with color highlighting. This can be easier for large changes.
git difftool: This command launches an external diff tool of your choice, such as Meld or Beyond Compare.
git diff –word-diff: Shows changes word-by-word rather than line-by-line, which is useful for prose.
git log -p: Shows the diff for each commit in the log, useful for reviewing history.

For comparing files outside Git, you can use the diff command on Unix-like systems, but git diff is more powerful because it understands Git’s object model and can compare any two commits or branches.

Frequently Asked Questions

Why does git diff show nothing when I have changes?

If you have staged your changes, git diff will not show them because it compares the working directory to the staging area. Use git diff --staged to see staged changes. Also, if the file is untracked, git diff will ignore it entirely.

How do I see changes between two commits?

Use git diff commit1 commit2. For example, git diff HEAD~2 HEAD shows changes from two commits ago to the current commit. You can also use branch names or tags.

What is the difference between git diff and git status?

git status gives a high-level summary of which files are modified, staged, or untracked. git diff shows the actual line-by-line content changes. You often use git status first to see what has changed, then git diff to inspect the details.

Can I save the diff output to a file?

Yes, you can redirect the output: git diff > changes.patch. This creates a patch file that you can share or apply later with git apply changes.patch.

How do I ignore whitespace changes in git diff?

Use git diff -w to ignore all whitespace changes, or git diff --ignore-space-at-eol to ignore changes at the end of lines. This is helpful when someone reindented code.

What does the `@@` line mean in the diff?

It is the hunk header. It tells you the starting line number and count in the old file and the new file. For example, @@ -5,3 +5,4 @@ means the old file had 3 lines starting at line 5, and the new file has 4 lines starting at line 5.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →