git diff: Usage, Options & Common CI Errors

git diff shows exactly what changed between any two states of your repository.

Diff is the core inspection tool. --exit-code and --name-only make it a precise gate in pipelines.

What it does

git diff compares two sources - working tree vs index, index vs HEAD, or any two commits/branches - and prints the line-level differences.

Common usage

Terminal

git diff                      # working tree vs index
git diff --staged             # index vs HEAD (a.k.a. --cached)
git diff main..feature
git diff --name-only HEAD~1
git diff --quiet || echo "changes present"

Options

Flag	What it does
--staged / --cached	Compare the index against HEAD
--name-only	List changed file names only
--name-status	Names plus add/modify/delete status
--stat	Summary of changes per file
--exit-code / --quiet	Exit non-zero if differences exist

Common errors in CI

A frequent gotcha: git diff alone ignores staged changes - use --staged to compare the index. With --exit-code, the command returns 1 when there are differences, which scripts may misread as failure; handle it deliberately (e.g. as a "needs formatting" signal).

Related guides

git status: Usage, Options & Common CI Errorsgit status shows staged, unstaged, and untracked changes plus branch state. Reference for -s, --porcelain, -b… git show: Usage, Options & Common CI Errorsgit show displays a commit, tag, or object with its diff. Reference for --stat, --name-only, blob viewing, an… git apply: Usage, Options & Common CI Errorsgit apply applies a patch file to the working tree or index. Reference for --check, --3way, --index, -p, and… git range-diff: Usage, Options & Common CI Errorsgit range-diff compares two versions of a commit series to show what changed between iterations. Reference fo…