git-ls-tree Tutorial

The short version

git-ls-tree is used to list entries inside a tree object.

When it is a good fit

• when you need to list entries inside a tree object
• when you want this step to be repeatable instead of ad hoc
• when you need a clearer mental model of what Git is recording or updating

Basic example

git ls-tree -r HEAD

What to watch most closely

Plumbing commands are closer to Git internals, so check whether a safer high-level command already solves the problem.

A safer working habit

Treat it as a read-only inspection tool first, then move to write-oriented usage only when necessary.

Useful angles for understanding it

• Inspect lower-level objects and refs
• Write scripts or debug advanced issues
• Verify internal repository state

Related reading

Read it alongside git status, git log, and git show so it is easier to see how the command changes history, refs, the index, or the working tree.

What problem this command solves in a workflow

git ls-tree solves the problem of "what files and directories does a given tree object contain?". It lists the directory and file entries inside a specified tree object, showing each entry's type, mode, and blob hash.

Typical use cases

• View the complete directory structure of a commit by running git ls-tree -r HEAD to recursively list all files and subdirectories.
• Parse the contents of a specific directory in a script by using git ls-tree HEAD:src/ to see file entries under a given path.
• Verify the blob hash of a file in a specific commit with git ls-tree HEAD path/to/file to retrieve its object ID.

Diagram view

Tree object

Tree object referenceRecursive optionTarget path

→git ls-tree

Outputs

File modeObject type (blob/tree)Object hashFile path

ls-tree only reads tree object contents without changing anything. It shows the directory structure at a specific snapshot moment.

Special cases and boundaries

• git ls-tree is a pure read-only command — it never modifies the object database, index, or working tree.
• By default it only shows the specified level of content; use -r (recursive) to list all files in subdirectories.
• You can use the TREE:PATH syntax to see contents under a specific path, such as git ls-tree HEAD:src/.
• Output includes file modes (e.g., 100644 for regular files, 100755 for executables, 040000 for directories).
• It shows the tree structure from the object database, independent of the working tree state — even if the working tree has uncommitted changes, ls-tree still shows the tree object's contents.