How to use the command git ls-tree (with examples)

The git ls-tree command is used to list the contents of a tree object in a Git repository. A tree object represents a directory and contains references to files or other tree objects. By using git ls-tree, you can inspect the contents of a tree at a specific branch or commit.

Use case 1: List the contents of the tree on a branch

Code:

git ls-tree branch_name

Motivation: When working on a specific branch in a Git repository, it can be useful to see the contents of the tree associated with that branch. This can help identify the files and directories present in the branch and track changes as they are made.

Explanation:

• git ls-tree: The command to list the contents of a tree.
• branch_name: The name of the branch whose tree contents you want to list. Replace branch_name with the actual name of the branch.

Example output:

100644 blob a906cb2a4a904a152e80877d4088654daad0c859    README.md
040000 tree 99f1d847ed276c8cdcab50f8a2f24f4f4f301bd1    src

The output displays the information of each entry in the tree. Each entry consists of a file mode, object type, object hash, and filename. In the example output, the tree contains a blob object (file) named README.md and a tree object (directory) named src.

Use case 2: List the contents of the tree on a commit, recursing into subtrees

Code:

git ls-tree -r commit_hash

Motivation: Sometimes, you may need to recursively check the contents of a tree on a specific commit, including its subdirectories and their contents. This can be handy when inspecting the complete state of a repository at a particular point in time.

Explanation:

• git ls-tree -r: The -r option tells Git to recurse into subtrees.
• commit_hash: The hash of the commit whose tree contents you want to list. Replace commit_hash with the actual commit hash.

Example output:

100644 blob a906cb2a4a904a152e80877d4088654daad0c859    README.md
040000 tree 99f1d847ed276c8cdcab50f8a2f24f4f4f301bd1    src
040000 tree 5824718ae8ea618e6d918c4935aaa5a7dca69ce2    tests
100644 blob eaf3c048a979b98bfcf38a07bcae87d2b569f579    LICENSE

The output contains the information of each entry in the commit’s tree. In this example, the tree includes a blob (file) named README.md, two tree objects (directories) named src and tests, and another blob (file) named LICENSE.

Use case 3: List only the filenames of the tree on a commit

Code:

git ls-tree --name-only commit_hash

Motivation: Sometimes, you might only need the filenames of the entries in a tree on a specific commit. This can be helpful, for instance, when you want to store a list of filenames for further processing or filtering.

Explanation:

• git ls-tree --name-only: The --name-only option makes Git only display the filenames.
• commit_hash: The hash of the commit whose tree filenames you want to list. Replace commit_hash with the actual commit hash.

Example output:

README.md
src
tests
LICENSE

The output contains only the filenames of the entries in the commit’s tree. In this example, the tree consists of the filenames of a file README.md, two directories src and tests, and a file LICENSE.

Use case 4: Print the filenames of the current branch head in a tree structure

Code:

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

Motivation: Visualizing the filenames and directory structure of a branch’s tree can be useful for understanding the organization of the files in the repository. The tree command is used here to display the output in a tree-like structure.

Explanation:

• git ls-tree -r --name-only HEAD: The command lists only the filenames of the current branch’s tree, regardless of their type (-r) and the reference is the HEAD commit. The output is then piped to the tree command.
• tree --fromfile: The --fromfile option tells the tree command to read the input as a list of filenames and print a tree-like structure.

Example output:

.
├── README.md
├── src
│   ├── main.c
│   ├── utils
│   │   └── helper.c
│   └── tests
│       └── test.c
└── LICENSE

2 directories, 5 files

The output shows the tree structure of the current branch’s files and directories. The files and directories are indented to reflect their hierarchical relationship. The tree command also provides a summary at the end, indicating the number of directories and files found.