git-read-tree

git read-tree [] [...]
git read-tree --empty
git read-tree --reset []
git read-tree --merge [-u | -m] []

--empty
    Empty the index. This option clears all current index contents.

--reset []
    Reset mode. Reads the tree into the index, replacing its current contents. If is omitted, it defaults to the HEAD tree.

-m, --merge
    Merge mode. Requires two or three arguments (common, ours, theirs). It attempts to merge the trees into the index. Conflicts will result in the index being left in a conflicted state.

-u, --update
    Updates the files in the working tree with the content of the index. This option is implied by --merge when the index is not already populated.

-i, --index-info
    Reads the index info. Useful when merging multiple trees that might have different file modes or names.

-v, --verbose
    Be verbose. Show progress information.

-n, --dry-run
    Dry run. Do not actually read the tree into the index or update the working tree. Only show what would be done.

--prefix=/
    Prepend / to the paths in the tree object. This is useful for placing a tree's contents into a subdirectory.

--aggressive
    (Deprecated for --merge mode, internal use only) Attempts an aggressive merge.

--no-sparse-checkout
    Do not enable sparse checkout even if the index format version is V4.

--recurse-submodules
    When reading a tree that contains submodules, recursively populate the contents of the submodule directory.

--no-recurse-submodules
    Do not recursively populate submodules. This is the default.

--trivial-merge-mode
    Use a trivial merge strategy (internal).

--no-trivial-merge-mode
    Do not use a trivial merge strategy (internal).


    An object name (e.g., commit, tree, tag) that refers to a tree object. One or more can be specified depending on the mode.

git-read-tree is a low-level plumbing command in Git used to read tree objects into the index. It directly manipulates the Git index, which is the staging area for the next commit. Unlike porcelain commands like git add or git commit, git-read-tree operates at a fundamental level, allowing advanced users or scripts to construct complex index states.

It can read one or more trees, merging them into the current index content based on specified options. This command is crucial for operations like git checkout, git merge, and git reset under the hood, as these commands often need to reconstruct the index from specific tree states. Its primary use is for building an index from a specific tree or trees, often to prepare for a commit or to set up a working directory.

git-read-tree is a plumbing command, meaning it's a low-level operation primarily for scripting or internal Git use. Direct manual use requires a deep understanding of Git's internal object model and index structure.

Incorrect use can lead to a corrupted index or unexpected working tree state, potentially requiring a git reset --hard to recover.

When used without -u or --merge -u, it only updates the index, not the working directory. Changes in the index will not be visible in your files until explicitly updated.

git-read-tree can operate in several distinct modes:
Simple Mode (git read-tree <tree-ish>): Reads the contents of a single tree into the index, overwriting its current contents. This is useful for completely replacing the index with a specific commit's tree state.

Merge Mode (git read-tree -m [<common-tree-ish>] <tree-ish-1> <tree-ish-2>): Attempts to merge two (or three, if a common base is provided) trees into the index. It performs a three-way merge if three tree-ishes are given, or a two-way merge otherwise. This is the underlying mechanism for git merge.

Reset Mode (git read-tree --reset [<tree-ish>]): Similar to simple mode, but explicitly states the intent to replace the index. If no <tree-ish> is given, it defaults to the tree from HEAD.

Empty Mode (git read-tree --empty): Clears the entire index, making it completely empty.

git-read-tree is one of the foundational plumbing commands in Git, present since its early development by Linus Torvalds. It's fundamental to how Git manages its staging area (the index) and performs operations like merging and checking out. Its core functionality has remained consistent, although options have been added over time to support new features like sparse checkout or submodule handling. It embodies Git's content-addressable filesystem nature, allowing direct manipulation of tree objects.

git-write-tree(1), git-commit-tree(1), git-update-index(1), git-ls-files(1), git-checkout-index(1), git-merge(1), git-reset(1)