Synopsis

git write-tree [--missing-ok] [--prefix=<dir>]

Description

The git write-tree command serializes the current index into a tree object in the database, returning the SHA. It is the plumbing inverse of read-tree: that command loads a tree, this one stores one.

In day-to-day use, git write-tree integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git write-tree --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.

Understanding how git write-tree interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git write-tree's side effects helps avoid all three.

When to Use

You almost never call this directly. git commit calls write-tree internally to capture the staged state. Reach for it when synthesizing tree objects for custom workflows (generating a tree without a commit, scripting commit-tree pipelines).

Common Options

Examples

git write-tree
# Print SHA of tree representing the current index

TREE=$(git write-tree)
COMMIT=$(echo "Snapshot" | git commit-tree "$TREE" -p HEAD)
git update-ref refs/heads/snapshot "$COMMIT"
# Manually craft a commit on a new branch

git write-tree --prefix=docs/
# Just the docs/ subtree

Common Mistakes

If the index has unmerged entries, write-tree fails. Resolve conflicts first. Forgetting that write-tree doesn't create a commit — only a tree — leads to dangling objects. git help write-tree opens the full manual page with comprehensive coverage of every option and edge case; it remains the authoritative reference whenever the summary on this page leaves a question unanswered. For team workflows, capturing how your project uses this command in a CONTRIBUTING document avoids repeated onboarding questions and keeps everyone aligned on conventions.

Related Commands

git read-tree, git commit-tree, git ls-tree, git update-index