git commit-tree

The atom of git commit. Take a tree SHA, get a commit SHA.

🎯 What & why

git commit-tree creates exactly one commit object in the object database from a given tree OID, optional parents, and a message. It is the single atom that git commit orchestrates around — porcelain just stages, writes a tree, calls commit-tree, and updates a ref.

🧠 Mental model

Pure object-DB writer. Input: a tree OID, zero-or-more -p parents, a message. Output: a commit object's SHA on stdout. It does NOT update HEAD, it does NOT touch any ref, and it does NOT consult the index. To 'do a commit by hand': write-tree -> commit-tree -> update-ref refs/heads/branch <new-sha>.

🛠️ Synopsis

git commit-tree <tree> [(-p <parent>)...]
                [-S[<keyid>]] [--no-gpg-sign]
                [(-m <message>)...] [(-F <file>)...]
                [< message-on-stdin]

🎚️ Switches & options

Flag	What it does
`<tree>`	Required. The tree OID whose snapshot this commit will point at — typically from `git write-tree`.
`-p <parent>`	Add a parent commit OID. Repeatable: zero parents = root commit, one = normal, two-or-more = merge.
`-m <msg>`	Commit message. Multiple `-m` become separate paragraphs (matching `git commit -m`).
`-F <file>`	Read the commit message from <file>. Use `-` to read from stdin.
`-S[<keyid>]`	GPG-sign the commit; optional <keyid> picks a key. The signature lives in the commit object header.
`--no-gpg-sign`	Override `commit.gpgSign=true` for this one invocation.

💡 Use cases

Reconstruct a commit by hand when scripting history surgery: write-tree then commit-tree then update-ref.
Create an octopus or synthetic merge with custom parents that no porcelain command would produce.
Build a root commit on a brand-new branch from an existing tree without checking anything out.
Author replayed/bespoke commits in tools like filter-repo, fast-import alternatives, or migration scripts.

🧪 Examples

Commit current index by hand

TREE=$(git write-tree); echo "msg" | git commit-tree $TREE -p HEAD

Root commit (no parents)

git commit-tree $(git write-tree) -m 'initial'

Synthetic merge of two tips

git commit-tree $TREE -p main -p feature -m 'merge'

Sign and update branch ref

SHA=$(git commit-tree $TREE -p HEAD -S -m 'signed'); git update-ref refs/heads/main $SHA

🎓 Recommendations

Always capture the printed SHA — it is the ONLY way to reach the new commit until you point a ref at it.
Pair commit-tree with git update-ref -m '<reason>' refs/heads/<branch> <new> <old> so the reflog records the move.
Set GIT_AUTHOR_ and GIT_COMMITTER_ env vars when scripting to keep author/committer metadata deterministic.

🪤 Common pitfalls

Commits created with no ref pointing at them are unreachable — gc will eventually delete them. Always update-ref promptly.
Forgetting -p HEAD produces a root commit (zero parents), severing history without warning.
commit-tree does not look at the index or worktree; if you forgot to write-tree after staging, you commit a stale snapshot.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.