git-write-tree

Create a tree object from the current index

$ git write-tree

$ git write-tree --missing-ok

$ git write-tree --prefix [subdirectory]/

git write-tree [--prefix=<path>]

--prefix=<path>
    Instead of writing the entire index as a tree object, write a tree object that represents the contents of the given path (and its subdirectories) in the index. The <path> must refer to a directory within the index. The resulting tree object will represent only that subdirectory and its contents.

git write-tree is a low-level Git "plumbing" command that reads the current content of the Git index and creates a new tree object in the Git object database. A tree object represents a directory and its contents at a specific point in time, storing references to blob objects (for file contents) and other tree objects (for subdirectories).

This command captures the snapshot of the staged changes, but it does not create a commit object. It only produces the tree object that a commit object would later reference. Higher-level commands like git commit internally use git write-tree to construct the tree component of a new commit.

For git write-tree to succeed, all necessary blob objects for the files and tree objects for the subdirectories (as represented in the index) must already exist in the object database. This is typically ensured by commands like git add, which writes the file contents as blobs to the database when staging.

This command operates strictly on the Git index, not the working directory. Any changes in the working directory that have not been staged (added to the index) will not be included in the generated tree object.

All necessary blob and subtree objects must already exist in the Git object database for git write-tree to succeed. If the index refers to objects that haven't been written (e.g., a file was added to the index but its content blob wasn't stored), the command will fail. (This is generally handled by git add).

It's a low-level command, not intended for direct daily use by end-users.

git write-tree is classified as a 'plumbing' command, meaning it's a low-level building block that operates directly on Git's internal data structures (like the index and object database). Most users interact with 'porcelain' commands like git commit, which use plumbing commands internally.

The command outputs the SHA-1 (or other configured hash algorithm, like SHA-256) hash of the newly created tree object to standard output upon successful completion. This hash is then typically used by other commands, such as git commit, to link the tree object to a commit.

git write-tree has been a fundamental component of Git since its early development. It serves as the core mechanism for capturing and storing the directory snapshots that form the basis of Git's version control. Its existence highlights Git's design philosophy of building powerful high-level commands upon a set of robust low-level 'plumbing' tools.

git add(1), git commit(1), git read-tree(1), git mktree(1), git ls-tree(1), git update-index(1)