git diff-index

What git diff --cached is built on.

🎯 What & why

git diff-index compares the index (or working tree) against an arbitrary tree-ish, usually a commit. It's what powers 'git diff --cached' and 'git diff HEAD'. If you need 'has anything changed since this commit?', this is the tool.

🧠 Mental model

Pick a tree on the left (any commit/tag/tree SHA), and either the index or the working tree on the right. Same output language as diff-files; just a different left-hand side.

🛠️ Synopsis

git diff-index [--cached] [--merge-base] [-p] [--raw] [--name-only] [-q]
               <tree-ish> [<path>...]

🎚️ Switches & options

Flag	What it does
`<tree-ish>`	The committed/tagged/tree SHA on the left side. Required.
`--cached`	Compare the index (not the working tree) to <tree-ish>. This is 'git diff --cached'.
`--merge-base`	Use the merge-base of HEAD and <tree-ish> as the left side instead.
`-p`	Produce a unified patch.
`--raw`	Machine-readable mode/SHA/status output (default-ish).
`--name-only`	Only print changed paths, one per line. Great for piping.
`-q / --quiet`	Silent; exit non-zero if any difference exists.

💡 Use cases

Implement 'is the working tree clean against HEAD?' in hooks: git diff-index --quiet HEAD.
List paths changed since a given tag: git diff-index --name-only v1.0.
Show staged-only changes against any base, not just HEAD.
Compare working tree to a historical commit ignoring index by omitting --cached.

🧪 Examples

Working tree vs HEAD (patch)

git diff-index -p HEAD

Staged vs HEAD (porcelain's --cached)

git diff-index --cached -p HEAD

Names changed since v1.0

git diff-index --name-only v1.0

Clean-tree gate in a hook

git diff-index --quiet HEAD || exit 1

🎓 Recommendations

'git diff-index --quiet HEAD' is the canonical clean-tree check; memorize it.
Use --name-only for fast file lists; faster and saner than parsing patch output.
Pair with --cached when you need staged-vs-tree without working-tree noise.

🪤 Common pitfalls

Without --cached it compares working tree (NOT the index) to the tree; easy to confuse.
Stat-dirty index can produce false positives; run 'git update-index --refresh' first in scripts.
<tree-ish> is mandatory; forgetting it errors out unlike bare 'git diff'.

🔗 Related modules

📝 Quiz

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