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 [] [...]

--full-name
    Show object names in full, relative to the repository root.

--name-only
    Show only the names of the entries, one per line.

--name-width=
    Display entry names padded or truncated to the specified width.

--abbrev[=]
    Abbreviate the object SHA-1 hashes to digits (default 7).

--long
    Show object sizes in bytes for blob entries.

--z
    Terminate entries with a NUL byte instead of a newline, useful for scripting.


    The tree object to inspect. Can be a commit, tag, branch name, or a direct tree hash.

...
    Optional paths to filter the output, showing only entries within these paths.

The git-ls-tree command is a "plumbing" command used to list the contents of a given tree object in Git. A tree object represents a directory in the Git repository, containing references to other tree objects (subdirectories) and blob objects (files).

For each entry in the specified tree, git-ls-tree outputs its mode, object type (blob, tree, or submodule), the SHA-1 hash of the object, and the filename. This command is crucial for understanding the exact state and structure of a directory at a particular point in history, without needing to check out the entire content. It's often used in scripts or for low-level repository inspection, allowing developers to programmatically navigate the Git object database. Unlike git ls-files, which lists files in the index, git-ls-tree operates directly on tree objects, which can be part of a commit, a tag, or even a standalone tree object.

git-ls-tree lists tree and blob objects as they are recorded in the Git database; it does not reflect the current state of the working directory or the index, unless the argument specifically points to the tree object associated with HEAD or the current index. Its output is optimized for machine parsing, making it less human-readable by default. Submodules are listed with mode `160000` and their commit SHA-1, not their internal contents.

git-ls-tree is considered a "plumbing" command, meaning it operates at a low level directly on Git's internal data structures. These commands are typically used by scripts or other Git commands rather than directly by end-users. This distinguishes it from "porcelain" commands, which are more user-friendly and abstract the underlying mechanics.

The output includes a mode field, which indicates the type of object and its permissions. Common modes include 100644 (regular file), 100755 (executable file), 040000 (subdirectory - another tree object), and 160000 (gitlink - a submodule).

git-ls-tree is a fundamental "plumbing" command that has been a core part of Git since its early development. Conceived by Linus Torvalds, Git was built around a content-addressable filesystem where all data (files, directories, commits) are objects identified by their SHA-1 hash. Commands like ls-tree were essential from the outset to inspect and interact with these basic object types. Its purpose, to list the contents of a tree object, directly reflects Git's internal data model, making it a stable and enduring utility within the Git command suite. Its primary use remains in low-level scripting and repository inspection, consistent with its original design as a building block for higher-level Git commands.

git cat-file(1), git show(1), git rev-parse(1), git read-tree(1), git write-tree(1), git ls-files(1)