Synopsis
git read-tree [-m | -u | --reset] <tree-ish>...Description
The git read-tree command loads tree contents into the index. Variants support merging up to three trees (a base, ours, theirs) for use during merges. git checkout, git merge, and git reset all use read-tree internally.
In day-to-day use, git read-tree integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git read-tree --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.
Understanding how git read-tree interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git read-tree's side effects helps avoid all three.
When to Use
Most users never need this. It's relevant for implementing custom merge tools, scripts that build the index from arbitrary trees, or for the git read-tree --prefix=<dir> trick to merge a subtree.
Common Options
| Option | Description |
|---|---|
-m | Three-way merge tree mode. |
-u | Update working tree to match index. |
--reset | Behave like reset --hard for the index. |
--prefix=<dir> | Read tree into a subdirectory. |
--empty | Empty the index. |
-i | Don't update working tree. |
Examples
git read-tree --empty
# Clear the index
git read-tree HEAD
# Re-populate index from HEAD's tree
git read-tree --prefix=lib/ -u other-branch:src
# Splice the src/ tree of another branch into lib/
git read-tree -m HEAD origin/main
# Merge two trees into the index (low-level merge)Common Mistakes
Calling read-tree without -u leaves the working tree out of sync with the index, surprising subsequent operations. Doing this in a busy worktree can cause confusing diffs.
Related Commands
git write-tree, git checkout, git merge, git update-index