git read-tree

What 'switch' uses to load a different tree into the index.

🎯 What & why

git read-tree loads one or more tree objects into the index. It is the low-level engine porcelain like switch, checkout, and merge calls to swap what the staging area thinks the tree looks like.

🧠 Mental model

The index is a flat manifest. read-tree rewrites that manifest from a tree (1-tree mode), fast-forwards it (2-tree mode), or runs a 3-way merge of common-ancestor + ours + theirs (3-tree mode).

🛠️ Synopsis

git read-tree [--reset] [-u] [-i] [--prefix=<dir>/]
              [-m [--aggressive]] [--no-sparse-checkout]
              <tree-ish> [<tree-ish> [<tree-ish>]]

1 tree-ish: replace index. 2 tree-ish: fast-forward. 3 tree-ish: merge.

🎚️ Switches & options

Flag	What it does
`--reset`	⚠️ Replace index unconditionally; discard unmerged entries and local index changes.
`-u`	Also update the working tree to match (otherwise WT is left stale).
`--prefix=<dir>/`	Read the tree into a subdirectory; index must be empty under that path.
`-i`	Do not refresh stat-cache; useful when WT will not be touched.
`-m`	Perform a merge (requires 2 or 3 tree-ish args).
`--aggressive`	Resolve trivial 3-way cases (one side unchanged) automatically.
`--no-sparse-checkout`	Ignore sparse-checkout patterns for this read.

💡 Use cases

Rebuild the index from HEAD after a corruption (git read-tree HEAD).
Stage a subtree at a prefix (subtree-merge style imports).
Implement custom switch/merge logic in scripts.
Set up the index for a fast-forward without running porcelain.

🧪 Examples

Reset index to HEAD (no WT touch)

git read-tree HEAD

Reset both index and working tree

git read-tree --reset -u HEAD

Read a tree into a subdirectory

git read-tree --prefix=vendor/foo/ <tree-sha>

3-way merge of three trees

git read-tree -m --aggressive $base $ours $theirs

🎓 Recommendations

Pair with -u whenever the working tree should follow the index, otherwise expect 'modified' noise.
Use --aggressive for scripted merges; it disposes of the boring trivial conflicts.
For everyday work, prefer git switch / git restore -- read-tree is a power tool.

🪤 Common pitfalls

Without -u, the working tree is NOT updated -- git status will look chaotic.
--reset silently throws away unmerged index entries; you can lose conflict resolutions.
--prefix requires that nothing already exists in the index at that path.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.