git diff: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

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).

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git diff: Usage, Options & Common CI Errors?