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.
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
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.
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:
<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.gitkeepto 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 fsckcomplain with aduplicateEntriesmessage. - Reading a path.
git rev-parse HEAD:src/main.cfollows trees from the commit down to the blob; the<rev>:<path>form works for trees too. - Recursive listing.
git ls-tree -rexpands sub-trees,-talso shows the tree entries themselves, and-ladds blob sizes. - Building trees.
git write-treecreates one from the index;git mktreecreates 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.