git diff

Compare the working tree, the index, and HEAD, plus --cached/--staged, --no-index, and exit codes, checked on Git 2.39.5.

命令页正文目前为英文。

git diff shows changes between two trees. The trees you usually compare are the working tree (files you edit), the index (the staging area), and HEAD (the last commit). This page is a command reference with verified examples, not a replacement for the command catalog or the introductory Git tutorial.

Examples were checked on Git 2.39.5 (Apple Git-154) in isolated temporary repositories. They use a fixed practice identity and fixed UTC dates, and they change only local repository configuration. --cached and --staged are the same option. Default git diff in a repository exits 0 even when it prints a patch; --exit-code, --quiet, and --no-index use diff-style exit codes.

Examples were checked against Git 2.39.5. See the official documentation for the complete command.

Git command catalog → · Git tutorial overview →

Working tree, index, and HEAD

Plain git diff compares the working tree with the index. It does not show staged changes. git diff --cached, also spelled --staged, compares the index with HEAD. git diff HEAD compares the working tree with HEAD, so it includes both staged and unstaged edits in the file contents.

The example stages a first edit, then adds a second unstaged line. The cached diff shows only the staged line, the plain diff shows only the unstaged line, and --cached and --staged produce identical patches. --name-status against HEAD reports the file as modified.

git diff, git diff --cached, git diff --staged, git diff HEAD

git diff [<options>] [<commit>] [--] [<path>...]
git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
git diff --staged

Compare the working tree with the index, the index with HEAD, or the working tree with HEAD.

ParameterDescription
--cached / --stagedCompare the index with HEAD, or with the given commit. The two option names are aliases.
HEADCompare the working tree with the current commit, including staged and unstaged file contents.
--unified=<n>Patch context lines. The example uses 0 to keep the output short and stable.

Returns: A patch or a name-status list on standard output. In a repository, the default exit status is 0 even when a patch is printed.

Exit status

  • 0 — The default git diff porcelain in a repository exits 0 after printing differences. This was measured on Git 2.39.5.
  • 1 — Returned when --exit-code or --quiet is used and the trees differ. The example prints that as plain-quiet-exit=1.
  • Inspect both the plain and the cached diffs before you commit. An empty plain diff can still hide staged changes.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'one\n' > file.txt
git add file.txt
git commit -m "Add file" >/dev/null
printf 'one\ntwo\n' > file.txt
git add file.txt
printf 'one\ntwo\nthree\n' > file.txt
echo "plain"
git diff --unified=0
git diff --quiet
echo "plain-quiet-exit=$?"
echo "cached"
git diff --cached --unified=0
cached=$(git diff --cached)
staged=$(git diff --staged)
if [ "$cached" = "$staged" ]; then echo "cached-equals-staged=yes"; else echo "cached-equals-staged=no"; fi
echo "HEAD-name-status"
git diff HEAD --name-status

Expected output

plain
diff --git a/file.txt b/file.txt
index 814f4a4..4cb29ea 100644
--- a/file.txt
+++ b/file.txt
@@ -2,0 +3 @@ two
+three
plain-quiet-exit=1
cached
diff --git a/file.txt b/file.txt
index 5626abf..814f4a4 100644
--- a/file.txt
+++ b/file.txt
@@ -1,0 +2 @@ one
+two
cached-equals-staged=yes
HEAD-name-status
M	file.txt

Related: git status, Git tutorial: Inspect changes and history

Official documentation →

--no-index and exit codes

git diff --no-index compares two files or directories on disk and does not require a repository. On Git 2.39.5 it exited 0 when the paths were identical, and it exited 1 both when the paths differed and when a path could not be accessed. A missing right-hand path printed an error on standard error and exited 1, not 2. Exit status 1 is therefore not enough to conclude that the files merely differ; read standard error as well. This page does not invent a portable error exit code such as 2, because that status was not observed in these measurements.

A repository git diff does not use those exit codes unless you pass --exit-code or --quiet. Do not treat a 0 exit from plain git diff as proof that the trees match.

git diff --no-index, git diff --exit-code, git diff --quiet

git diff [<options>] --no-index [--] <path> <path>
git diff --exit-code
git diff --quiet

Compare two paths without a repository, and use diff-style exit codes.

ParameterDescription
<path> <path>The two files or directories to compare. -- separates them from options.
--quietSuppress the patch and imply --exit-code.

Returns: A patch when the paths differ and --quiet is not used. Identical files produce no patch.

Exit status

  • 0 — --no-index exits 0 when the two paths have the same content.
  • 1 — On Git 2.39.5, both a content difference and a missing path exited 1. A 1 does not by itself mean the files differ; the missing-path case also printed an error to standard error. Do not treat 1 as a universal “differ” code, and do not assume a different status for errors unless you have measured it.
  • The missing-file error text comes from Git itself and was captured with 2>&1. These measurements did not produce exit status 2. Other Git versions or path kinds may differ; check stderr before you interpret a 1.
bash
mkdir -p cmp
printf 'a\n' > cmp/left.txt
printf 'a\n' > cmp/same.txt
printf 'b\n' > cmp/right.txt
git diff --no-index -- cmp/left.txt cmp/same.txt
echo "same-exit=$?"
git diff --no-index --unified=0 -- cmp/left.txt cmp/right.txt
echo "diff-exit=$?"
git diff --no-index --quiet -- cmp/left.txt cmp/right.txt
echo "quiet-diff-exit=$?"
git diff --no-index -- cmp/left.txt cmp/missing.txt 2>&1
echo "missing-exit=$?"

Expected output

same-exit=0
diff --git a/cmp/left.txt b/cmp/right.txt
index 7898192..6178079 100644
--- a/cmp/left.txt
+++ b/cmp/right.txt
@@ -1 +1 @@
-a
+b
diff-exit=1
quiet-diff-exit=1
error: Could not access 'cmp/missing.txt'
missing-exit=1

Official documentation →