git ls-tree

ls(1) for git trees.

🎯 What & why

List entries in a tree object: paths, modes, types, and SHAs. Think ls(1) for git's content-addressable tree, not the working directory.

🧠 Mental model

A tree is a flat directory listing pointing at blobs and other trees. ls-tree reads one tree-ish and prints its entries; -r flattens it like a recursive ls -R against history rather than disk.

🛠️ Synopsis

git ls-tree [-d] [-r] [-t] [-l] [-z]
            [--name-only] [--object-only] [--full-name] [--full-tree]
            [--abbrev[=<n>]]
            <tree-ish> [<path>...]

🎚️ Switches & options

Flag	What it does
`<tree-ish>`	Commit, tag, branch, or raw tree SHA to read.
`-r`	Recurse into sub-trees (flatten the listing).
`-d`	Show only directory (tree) entries.
`-t`	Show tree entries even when recursing with -r.
`-l, --long`	Add blob size as a fifth column (- for trees).
`--name-only`	Print just the path; useful for piping.
`--object-only`	Print just the SHA; pair with xargs cat-file.
`--abbrev=<n>`	Abbreviate SHAs to <n> hex chars.
`--full-name`	Print paths from the repo root, not the cwd.
`--full-tree`	Behave as if run from the repo root (path args become absolute-in-repo).
`-z`	NUL-terminate paths; safe for filenames with newlines.

💡 Use cases

Inspect what a commit's tree contains without checking it out.
List every tracked path at a tag for an audit or release diff.
Pipe blob SHAs into cat-file to grep historical content.
Find the on-disk size a file had at an old revision (-l).

🧪 Examples

Top-level entries of HEAD

git ls-tree HEAD

All files at a tag, recursive

git ls-tree -r v1.2.0

Sizes for blobs in a subdir

git ls-tree -lr HEAD -- src/

Just the paths, NUL-safe

git ls-tree -r -z --name-only HEAD

🎓 Recommendations

Reach for ls-tree when you need committed state; ls-files is for the index, plain ls is for the working tree.
Use --full-tree in scripts so behaviour does not depend on the cwd inside the repo.

🪤 Common pitfalls

Without -r you only see the top of the tree; nested files are hidden behind tree entries.
The path filter is a prefix match against repo-root paths once --full-tree is on; without it, paths are relative to cwd.

🔗 Related modules

📝 Quiz

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