Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Plumbing Commands

git read-tree command

Reference for git read-tree: load one or more tree objects into the index, merge trees with -m, use --prefix and -u, and see how it differs from checkout.

git read-tree reads the contents of a tree object and stores them in the index. Nothing else changes by default: no files are written to the working tree, no branch moves. It is the low-level "fill the staging area from this snapshot" operation, and the counterpart of git write-tree, which turns the index back into a tree.

With -m the command performs a one-, two- or three-tree merge into the index, which is the machinery behind git merge, git checkout and git reset inside Git itself. With --prefix you can graft a tree into a subdirectory of the index, which is how subtree-style tricks work.

Terminal
git read-tree <tree-ish>
git read-tree -m -u <tree-ish>
git read-tree --prefix=lib/ <tree-ish>

Try it

Bash Load a tree into the index only

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 Graft a tree under a prefix, then write 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.

Syntax

Terminal
git read-tree [-m [--trivial] [--aggressive] | --reset | --prefix=<prefix>]
              [-u | -i] [--index-output=<file>] [--no-sparse-checkout]
              (--empty | <tree-ish1> [<tree-ish2> [<tree-ish3>]])
Name Description
<tree-ish> One to three trees (a tree ID, a commit, a branch). Without -m, only one is allowed.
-m Merge. One tree: replace the index by it, keeping stat data. Two trees: a fast-forward style switch from the first to the second. Three trees: a three-way merge (base, ours, theirs).
-u After a successful merge, update the working tree to match. Requires -m or --reset.
-i Merge only the index; do not look at the working tree.
--reset Like -m, but discard unmerged entries instead of failing.
--prefix=<prefix> Place the tree below this directory (must end in /). The paths must not exist in the index already.
--empty Empty the index.
--index-output=<file> Write the resulting index to another file instead of the real one.
--aggressive In a three-way merge, also resolve cases such as "removed on one side, unchanged on the other".
--trivial Only resolve merges where all three versions agree trivially; leave the rest unmerged.

Returns: nothing on success, exit code 0.

Errors: with -m, a non-zero exit and an error such as "Entry ... would be overwritten" when the index or working tree has local changes that the operation would lose. --prefix fails with "Entry ... overlaps" if the path is already in the index.

Usage notes

  • Index only by default. Without -u, the working tree is not touched, so git status will show your files as modified or untracked afterwards. Add -u together with -m to make both match.
  • Three-way merge in the index. git read-tree -m <base> <ours> <theirs> leaves conflicts as stage 1, 2 and 3 entries, which you can see with git ls-files --stage and resolve with git merge-file and git update-index.
  • Temporary indexes. Pair --index-output or the GIT_INDEX_FILE environment variable with read-tree to build a tree without disturbing your real staging area.
  • Not a checkout. git checkout <branch> also moves HEAD. read-tree -m -u does not, so the repository ends up in a state that Git considers "modified".
  • Prefix must end in a slash and the target path must be free; this is a common cause of failures when grafting a directory twice.
  • Day-to-day use is rare. Prefer git restore --staged or git reset for normal work; reach for read-tree in scripts and when exploring how the index works.