git diff-tree: Usage, Options & Common CI Errors

git diff-tree compares the contents of two tree objects at the plumbing level.

When a hook or pipeline needs the exact list of files a commit changed, diff-tree is the stable, scriptable answer. It is the engine behind much of git log and is common in post-receive hooks.

What it does

git diff-tree compares two tree objects (or the trees of two commits) and prints the differences. With -r it recurses into subtrees, and its output format is stable enough to parse in scripts.

Common usage

Terminal

git diff-tree -r --name-only HEAD
git diff-tree --no-commit-id --name-only -r <sha>
git diff-tree -r <old-sha> <new-sha>
git diff-tree --root -r <first-commit>

Options

Flag	What it does
-r	Recurse into subtrees
--name-only	Print only changed file names
--name-status	Names plus add/modify/delete status
--no-commit-id	Omit the leading commit SHA line
--root	Show the full diff for a root commit

Common errors in CI

A root (first) commit prints nothing because it has no parent; pass --root to diff it against the empty tree. Forgetting --no-commit-id leaves the commit SHA as the first output line, which then leaks into file lists when scripts read line by line.

Related guides

git diff: Usage, Options & Common CI Errorsgit diff shows changes between commits, the index, and the working tree. Reference for --staged, --name-only,… git ls-tree: Usage, Options & Common CI Errorsgit ls-tree lists the contents of a tree object - files, modes, and ids. Reference for -r, --name-only, -l, a… git whatchanged: Usage, Options & Common CI Errorsgit whatchanged lists commits with the files each one touched. Reference for --oneline, -p, path limiting, an… git cat-file: Usage, Options & Common CI Errorsgit cat-file inspects Git objects - their type, size, and content. Reference for -t, -s, -p, --batch, and the…