git-ls-tree

List the contents of the tree on a branch

$ git ls-tree [branch_name]

$ git ls-tree -r [commit_hash]

$ git ls-tree --name-only [commit_hash]

$ git ls-tree -r --name-only HEAD | tree --fromfile

git ls-tree [options] [--] <tree-ish> [<path>…]

-r, --recursive
    Recurse into subtrees, listing all entries.

-t, --tree
    Show tree objects as well as blobs (default without -r).

-l, --long
    Show object type, size, and name in long format.

-d
    Only list tree objects (directories).

--full-tree
    Pretend as if all refs/heads/ refs are listed on command line.

-z
    Terminate entries with NUL, not newline; paths output with NUL too.

--name-only
    List only filenames (mode, type, sha1 omitted).

--name-status
    List filenames and status (like git-diff --name-status).

--full-name
    Use full pathname from repository root.

-u, --unquoted
    Print unquoted paths even if special chars present.

--abbrev[=<n>]
    Abbreviate object names to first <n> hex chars.

--format=<format>
    Output using custom format string (e.g., %(objectname)%x00%(path)).

--find-renames[=<n>]
    Detect renames; limited utility without paths.

The git ls-tree command is a plumbing utility in Git that displays the contents of a tree object, which represents a directory snapshot in the Git object database. It outputs entries in a format showing the mode, object type, SHA-1 hash, and filename for each item.

By default, it lists only top-level entries with a space-separated format: mode SP type SP sha1 TAB name. This makes it ideal for scripting and parsing in automation tasks, such as generating file lists from specific commits or tags without checking out the code.

Common use cases include inspecting historical tree states, feeding data into other Git commands, or integrating with build systems. For example, querying a commit's tree reveals exactly which files existed at that point, aiding in debugging or auditing changes. Unlike git ls-files, which operates on the index, git ls-tree works directly on committed trees, making it non-destructive and repository-wide.

Options allow customization: recursion into subdirectories, verbose details like file sizes, or filtered output by object type (blobs or trees). It's efficient for large repositories as it avoids full checkouts.

Designed as plumbing command; output parsing required for scripts. Does not follow symlinks. Use -- to separate options from paths with dashes.

Each line: mode type sha1 path, e.g., 100644 blob a906cb2a4a904a152e80877d4088654daad0c859 README.

git ls-tree HEAD lists root tree of HEAD.
git ls-tree -r --name-only HEAD: all files recursively.
git ls-tree -l v2.6.14 src/ details src/ at tag v2.6.14.

Introduced in early Git (v1.0.0, 2005) by Linus Torvalds as core plumbing for tree inspection. Evolved with format options in v1.5+ for scripting flexibility; remains stable for backward compatibility.

git-ls-files(1), git-cat-file(1), git-rev-list(1), git-ls-remote(1), ls(1), tree(1)