Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Plumbing Commands

git ls-tree command

Reference for git ls-tree: list files and directories stored in a tree, use -r, -l, --name-only and --format, and read modes, types and object IDs.

git ls-tree prints the entries of a tree object: one line per file, directory, symlink or submodule, with its mode, type, object ID and name. A tree is what a commit points at, so git ls-tree HEAD shows the files in the latest commit, independent of what is in your working directory or index.

It is the right tool for scripts that need to know what a particular commit contains, and for peeking at a snapshot without checking it out.

Terminal
git ls-tree HEAD
git ls-tree -r --name-only main
git ls-tree -l HEAD docs/

Try it

Bash Top level versus recursive

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Choose your own format and look at one folder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git ls-tree [-d] [-r] [-t] [-l] [-z] [--name-only | --name-status | --object-only]
            [--full-name] [--full-tree] [--abbrev[=<n>]] [--format=<format>]
            <tree-ish> [<path>...]
Name Description
<tree-ish> A tree, commit, branch or tag. A commit is peeled to its tree.
<path>... Limit output to these paths (relative to the current directory when run in a subfolder). A trailing / lists the directory's contents.
-r Recurse into subtrees and list only files.
-t With -r, also show the tree entries.
-d Show only the tree entries (directories), not files.
-l, --long Add the blob size (bytes) as a column; - for trees.
--name-only, --name-status Print only the path.
--object-only Print only the object ID.
--abbrev[=<n>] Shorten object IDs.
-z NUL-terminate lines and do not quote names.
--full-name, --full-tree Show paths relative to the repository root instead of the current folder.
--format=<format> Template with %(objectmode), %(objecttype), %(objectname), %(objectsize), %(objectsize:padded) and %(path).

Returns: lines of the form <mode> SP <type> SP <object> TAB <path>.

Errors: "Not a valid object name" for an unknown revision; "not a tree object" when a blob is given.

Usage notes

  • Modes you will see: 100644 regular file, 100755 executable, 120000 symlink, 040000 tree, 160000 submodule commit (type commit).
  • Not recursive by default. A bare git ls-tree HEAD lists only the top level; directories appear as tree entries. Add -r for all files.
  • Directory paths need care. docs matches the entry docs, while docs/ matches the contents of the folder. With -r, both forms list the files inside.
  • Reads the repository, not the disk. For what is staged now, use git ls-files --stage; for what is on disk, use plain ls.
  • Quoting: names with unusual bytes are printed in C-style quotes unless you use -z.
  • Round trip: the default output is exactly what git mktree accepts.
  • Version note: --format and --object-only were added in Git 2.36.