git-subtree

name	git-subtree
description	Vendor external dependencies into a monorepo using git subtree. Use when adding, updating, or managing vendored third-party code, soft forks (pull-only), or push-pull subtrees for self-owned repos. Covers interaction with jujutsu (jj) colocated workflows.

Git Subtree Vendoring

Vendor dependencies as plain directories — no submodule indirection, works with any tool that reads files.

Two Modes

Mode	Use case	Operations	Example
Pull-only (soft fork)	Third-party libs you patch locally	add, pull	vendoring an OSS library
Push-pull	Repos you own / can push to	add, pull, push	shared internal library

Choose pull-only by default. Upgrade to push-pull only when you actually need to upstream changes.

Setup: Register a Remote

Always register a named remote so the URL isn't repeated:

git remote add <name> <url>
git fetch <name>

Convention: prefix vendor remotes with vendor/ or v- to distinguish them from origin/upstream (e.g. vendor/foo, v-foo).

Add a Subtree

git subtree add --prefix=<path> <remote> <branch> --squash

• --prefix — destination directory (e.g. vendor/foo, lib/bar)
• --squash — collapse the upstream history into a single merge commit (always use for pull-only; recommended for push-pull unless you need full history)

Example:

git remote add vendor/arrow https://github.com/apache/arrow.git
git fetch vendor/arrow
git subtree add --prefix=vendor/arrow vendor/arrow main --squash

Pull (Update) a Subtree

git fetch <remote>
git subtree pull --prefix=<path> <remote> <branch> --squash

--squash keeps each pull as one merge commit — clean, bisectable history.

Push Changes Upstream (push-pull only)

git subtree push --prefix=<path> <remote> <branch>

This extracts commits touching <path>, rewrites them relative to the subtree root, and pushes. Only meaningful for repos you control.

Keeping a Clean History

Always squash on pull

--squash is the single most important flag. Without it every upstream commit lands in your log. With it each add/pull is one merge commit.

Commit discipline

1. Separate vendoring from feature work. Do subtree add/pull in their own commits — never mix with unrelated changes.
2. Descriptive messages. The auto-generated squash message is fine; append context if needed:

   Squashed 'vendor/foo/' changes from abc123..def456
   
   Pulls in fix for CVE-2025-XXXX
   

3. Avoid rebasing subtree merge commits. Rebase will flatten the merge and break future subtree pull. If you must reorder history, keep subtree merges intact.

Periodic re-add (nuclear option)

If subtree tracking state gets corrupted (pull fails with cryptic merge errors):

git rm -r <path>
git commit -m "Remove vendor/foo for re-add"
git subtree add --prefix=<path> <remote> <branch> --squash

Jujutsu Interaction

jj colocated repos share the .git directory, but git subtree is a git-porcelain command. Run subtree operations through git directly — jj sees the result as normal file changes.

Workflow

# 1. Start from a clean jj working copy
jj new -m "Pull vendor/foo update"

# 2. Run subtree commands with git
git fetch vendor/foo
git subtree pull --prefix=vendor/foo vendor/foo main --squash

# 3. jj picks up the changes automatically.
#    The git merge commit from subtree pull is visible to jj.
#    Verify with:
jj st
jj log --limit 5

# 4. If the subtree pull created a merge commit in git,
#    jj may show it as a separate change. Squash if desired:
jj squash

# 5. Describe and move on
jj describe -m "Update vendor/foo to <version/date>"
jj new

Caveats

• Do not jj rebase across subtree merge commits — same as with git rebase, this destroys the merge structure subtree relies on.
• git subtree split/push creates temporary refs; run jj git import afterwards if jj doesn't pick them up automatically.
• Conflicts during subtree pull are resolved in git's working tree. After resolution, git commit to complete the merge, then let jj import.

Quick Reference

Task	Command
Register remote	git remote add vendor/X <url> && git fetch vendor/X
Add subtree	git subtree add --prefix=vendor/X vendor/X main --squash
Update subtree	git fetch vendor/X && git subtree pull --prefix=vendor/X vendor/X main --squash
Push upstream	git subtree push --prefix=vendor/X vendor/X main
Check remotes	git remote -v
Re-add (broken state)	git rm -r vendor/X && git commit -m "rm" && git subtree add ...