git diff-files

What git diff (no args) is built on.

🎯 What & why

git diff-files compares the working tree against the index (staged content). It's the engine under bare 'git diff' (no args) and is the canonical way for scripts to ask 'what's modified but not yet staged?'

🧠 Mental model

Two sides: index (left) and working tree (right). For unmerged paths it sees stages 1/2/3 (base/ours/theirs) and can show the relevant view of conflicts.

🛠️ Synopsis

git diff-files [-p] [-u] [-q] [--raw] [-1|-2|-3|-c|--cc]
               [--base|--ours|--theirs] [--ita-invisible-in-index] [<path>...]

🎚️ Switches & options

Flag	What it does
`-p / -u`	Generate a unified patch (text diff). Same as 'git diff' output.
`-q`	Silent; exit non-zero if any difference exists. Great for scripts.
`--raw`	Default-ish machine-readable format: mode/sha/status per path.
`-1 / -2 / -3 (--base/--ours/--theirs)`	For unmerged paths, diff against that conflict stage only.
`-c / --cc`	Combined / dense-combined diff for merge conflicts (multi-parent view).
`--ita-invisible-in-index`	Treat 'intent-to-add' (git add -N) entries as not-yet-in-index.

💡 Use cases

Script: detect any unstaged modifications cheaply with -q.
Generate machine-readable raw diff output for tooling.
Inspect just one side of a conflict (--ours / --theirs).
Reproduce 'git diff' output deterministically without porcelain config influence.

🧪 Examples

Show unstaged patch

git diff-files -p

Quiet check in a script

git diff-files --quiet || echo 'dirty tree'

Raw machine format

git diff-files --raw

Look at 'theirs' for conflicts

git diff-files --theirs path/to/conflicted

🎓 Recommendations

Use diff-files -q in CI/hooks; it's faster and stabler than parsing diff text.
Prefer --raw over -p when piping into other tools; it's stable across versions.
Remember: this is what porcelain runs; learning it makes 'git diff' demystify.

🪤 Common pitfalls

Without -p you get raw output, which surprises people who expect a patch by default.
Intent-to-add (-N) files appear staged unless you pass --ita-invisible-in-index.
Doesn't compare to HEAD; for that use diff-index. Scope matters.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.