Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Objects, Refs and Internals

Tree objects

Reference for Git tree objects: the binary entry layout, file modes, why directories sort as if they ended in a slash, and how to build and read trees by hand.

A tree object is Git's version of a directory. It is a list of entries, and each entry gives a mode, a name and the ID of another object: a blob for a file or symlink, another tree for a sub-directory, or a commit for a submodule. A commit points at exactly one top-level tree, so a tree (together with everything below it) is a complete snapshot of the project.

Because the ID of a tree is computed from its entries, two directories with identical names, modes and content have the same tree ID anywhere in history. This is how Git can tell instantly that a whole folder did not change between two commits: the tree ID is the same, so nothing underneath needs to be compared.

Terminal
git ls-tree HEAD              # entries of the root tree
git cat-file -p HEAD^{tree}   # the same listing, via cat-file
git write-tree                # turn the index into a tree

Try it

Bash Read the entries of a tree

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 Sorting: a directory is compared as if its name ended in a slash

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.

Format

The content of a tree object is a concatenation of entries with no separators and no header beyond the usual tree <size> NUL prefix used for every object (see Loose object format). Each entry is:

TEXT
<mode> SP <name> NUL <20-byte binary object ID>
Part Description
mode An ASCII octal number without leading zeros, so a directory is written 40000 inside the object even though git ls-tree prints 040000.
name A single path component in raw bytes, never containing / or NUL.
ID The object name in binary: 20 bytes for SHA-1, 32 bytes for SHA-256. It is not hexadecimal text.

Modes

Mode Meaning
100644 Regular file.
100755 Executable file.
120000 Symbolic link; the blob holds the link target.
040000 Sub-tree (directory).
160000 Gitlink: a submodule, whose ID is a commit in another repository.

Git only records whether the executable bit is set. Group and other permissions, owner and timestamps are not stored.

Ordering

Entries are sorted by name, byte by byte, with one twist: a tree entry is compared as if its name had a trailing /. That is why the directory a sorts after the files a-b and a.b (the characters - and . come before / in ASCII), although plain string comparison would put it first. If the order is wrong, the tree has the wrong ID and git fsck reports treeNotSorted.

Usage notes

  • No empty directories. A tree can technically be empty (the empty tree has the fixed SHA-1 ID 4b825dc642cb6eb9a060e54bf8d69288fbee4904), but Git never creates a tree entry for an empty working directory. Add a placeholder file such as .gitkeep to track a folder.
  • Names are bytes. Git does not interpret encodings. Case differences matter in the tree even on case-insensitive file systems, which is the source of many cross-platform surprises (see core.ignorecase).
  • Duplicate names are invalid. Two entries with the same name make git fsck complain with a duplicateEntries message.
  • Reading a path. git rev-parse HEAD:src/main.c follows trees from the commit down to the blob; the <rev>:<path> form works for trees too.
  • Recursive listing. git ls-tree -r expands sub-trees, -t also shows the tree entries themselves, and -l adds blob sizes.
  • Building trees. git write-tree creates one from the index; git mktree creates one from text.
  • Cost. Changing one file rewrites every tree on the path from the root to that file, so deep directories cost slightly more storage per commit than flat ones.