git-read-tree Tutorial

The short version

git-read-tree is used to read tree objects into the index for lower-level operations.

When it is a good fit

• when you need to read tree objects into the index for lower-level operations
• when you want this step to be repeatable instead of ad hoc
• when you need a clearer mental model of what Git is recording or updating

Basic example

git read-tree --reset -u HEAD

What to watch most closely

Plumbing commands are closer to Git internals, so check whether a safer high-level command already solves the problem.

A safer working habit

Treat it as a read-only inspection tool first, then move to write-oriented usage only when necessary.

Useful angles for understanding it

• Inspect lower-level objects and refs
• Write scripts or debug advanced issues
• Verify internal repository state

Related reading

Read it alongside git status, git log, and git show so it is easier to see how the command changes history, refs, the index, or the working tree.

What problem this command solves in a workflow

git read-tree solves the problem of "loading a tree object's contents into the index for low-level operations". It loads the directory structure of a specified commit or tree object into the index, and is the low-level foundation for Git's internal merge, reset, and branch-switching operations.

Typical use cases

• Reset the index to a commit's state by running git read-tree --reset -u HEAD to synchronize the index and working tree to HEAD's tree.
• Implement custom merge logic in a low-level script by using git read-tree -m HEAD branch1 branch2 to merge multiple trees into the index.
• Prepare a new index state and then use git write-tree to generate a new tree object, building a custom commit flow.

Diagram view

Tree object

Target tree/commitMerge mode (--reset / -m / -u)Current index state

→git read-tree

Results

Updated indexMerge conflict markers (if applicable)Working tree changes (if -u used)

read-tree directly modifies the index — it is a low-level write operation. When using -u, it also updates working tree files, requiring extra caution.

Special cases and boundaries

• git read-tree is a write operation that directly modifies index content. After execution, the index is replaced or merged, affecting subsequent commit behavior.
• When the -u (update) flag is used, read-tree also updates working tree files to match the new index state, which can overwrite uncommitted local changes.
• Multi-tree merge mode (-m) marks conflict entries in the index, requiring manual resolution before a new commit can be created.
• read-tree operates on the index rather than directly on the working tree (unless -u is used) — understanding the relationship between tree, index, and working tree is important.
• Unless you are writing low-level scripts or implementing custom Git operations, you should typically use higher-level commands like git reset or git checkout instead.