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

git ls-tree lists the files and subtrees recorded in a commit or tree object.

When you need the file layout of a specific commit - not the working tree - ls-tree reads it straight from the object store, including modes and blob ids, which is perfect for build manifests.

What it does

git ls-tree shows the entries of a tree object: each line carries the file mode, object type, object id, and path. With -r it recurses into subtrees.

Common usage

Terminal

git ls-tree HEAD
git ls-tree -r HEAD --name-only
git ls-tree -r -l HEAD            # include blob sizes
git ls-tree HEAD:src/            # contents of a subdirectory

Options

Flag	What it does
-r	Recurse into subtrees
--name-only	Print only paths
-l / --long	Include blob sizes
-d	Show only tree entries (directories)
-z	NUL-terminate output lines

Common errors in CI

fatal: not a tree object - you passed a blob or an invalid ref; use a commit, a tree, or <rev>:<path> that resolves to a directory. Without -r, only top-level entries appear, so subdirectory files seem "missing"; add -r for the full file list.

Related guides

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… git diff-tree: Usage, Options & Common CI Errorsgit diff-tree is the plumbing command that compares two tree objects. Reference for -r, --name-only, --no-com… git ls-files: Usage, Options & Common CI Errorsgit ls-files lists files Git knows about in the index. Reference for --others, --modified, --exclude-standard… 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…