git-read-tree

git read-tree [options] [--] <tree-ish> [<tree-ish> ...]

-m, --merge
    Perform a merge of multiple trees into index (default for >1 tree)

-r, --reset
    Reset index entries to match the tree exactly

-u, --update
    Update working tree files to match index after read-tree

-v, --verbose
    Enable verbose output

-d, --debug
    Enable debug output

--dry-run
    Dry run; do not modify index or working tree

--aggressive
    Aggressively resolve trivial merge conflicts (with -u)

--prefix=<prefix>/
    Read tree into index under given path prefix

--no-sparse-checkout
    Disable sparse-checkout patterns

-q, --quiet
    Suppress progress reporting

--index-version=<n>
    Write index in specified format version (2 or 3)

--exclude-per-directory=<name>
    Ignore .git/info/exclude-like files named <name>

--empty
    Start with empty index before reading tree

-i
    Use merging strategy optimized for submodules

git read-tree is a low-level Git plumbing command that reads one or more tree-ish objects (trees, commits, tags resolving to trees) and populates the index file (staging area) with their contents.

It supports several modes:
• Single tree-ish: Replaces the entire index with the tree's entries.
• Multiple tree-ish with -m: Merges trees into the index, resolving conflicts like in git merge.
• -r or --reset: Resets index to match the tree exactly.

Key features include prefixing paths (--prefix), sparse-checkout support, dry-run testing (--dry-run), and verbose/debug output. By default, it does not update the working tree; use -u or --update for that.

Primarily used internally by higher-level commands like git checkout, git merge, and git switch. Direct use is rare but useful in scripts for custom index manipulation. Caution: it can overwrite index entries, potentially losing staged changes.

Overwrites index without warning; backs up via GIT_INDEX_FILE. Does not touch working tree unless -u. Uncommitted index changes may be lost. Avoid direct use; prefer high-level commands.

Tree-ish arguments: any object resolving to a tree (SHA, branch, tag, HEAD, etc.). Multiple enable merging.

Respects .git/info/sparse-checkout unless --no-sparse-checkout. Limits index population to specified paths.

Introduced in Git v0.99 (2005) by Linus Torvalds as core plumbing. Evolved with merge modes (v1.5+), sparse-checkout (v1.7+), index v3 (v1.8+). Essential for Git's internal checkout/merge logic.

git-write-tree(1), git-ls-tree(1), git-checkout-index(1), git-update-index(1), git-checkout(1)