A drop-in replacement for git subtree, written in Go.
The goals are, in order:
- Compatible: the same commands, options, output conventions, and
synthetic split commit IDs as
contrib/subtree/git-subtree.sh. - Secure: no shell, no
eval, no word splitting, strict validation of prefixes, refs, revisions, repository arguments, and commit-message trailers. - Reliable: idempotent cache entries, atomic object writes, transactional
add, deterministic results, and clear errors. - Fast: batched
git cat-file, in-memory ancestry, a native commit writer, and a durable split cache.
This implementation targets current git.git contrib/subtree (Git 2.53) plus
the duplicate-cache fix that the older pre-2.32 script happened to tolerate.
Implemented:
add,merge,pull,push,split--prefix,--squash,--message,--annotate,--onto,--rejoin,--ignore-joins,--branch,-q/--quiet,-d/--debug,-S/--gpg-sign- SHA-1 and SHA-256 repositories
- bare repositories for
split - durable split cache with warm-tip fast path
- native commit writing with
git commit-treefallback for signed or unusual commits - strict prefix/ref/revision/repository validation
- OID-only trailer fetching (a malicious
git-subtree-splitrefspec cannot create or update local refs)
make build
make test
make test-raceInstall the standard hooks once per clone:
pre-commit install --hook-type commit-msg --hook-type pre-push
pre-commit run --all-filesThe GitLab pipeline runs the shared tooling/pipelines lint-conform,
pre-commit-enforce, golang-govet, golang-staticcheck, golang-test,
golang-build-linux, and autorel jobs. It pins GOLANG_VERSION to
1.26.10.
The integration tests run the vendored pre-2.32 reference script
(testdata/git-subtree.orig) and compare the full reachable commit graph, so
the expected hashes are checked against the implementation users actually have
today.
Git finds git-subtree in $(git --exec-path) before PATH. Installing there
is therefore the real drop-in install:
sudo make install # installs to $(git --exec-path)For a canary install that does not touch the system copy:
make install-canary # prints the canary exec path
GIT_EXEC_PATH=<canary> git subtree ...Back up the existing script before replacing it:
cp "$(git --exec-path)/git-subtree" /tmp/git-subtree.pre-goExactly like git subtree:
git subtree add --prefix=libs/foo https://example.com/foo.git main
git subtree pull --prefix=libs/foo https://example.com/foo.git main
git subtree push --prefix=libs/foo https://example.com/foo.git main
git subtree split --prefix=libs/foo --branch=foo-split HEAD
git subtree merge --prefix=libs/foo --squash <commit>split prints only the resulting commit hash on stdout. Progress, debug
messages, and the Added dir/Created branch messages go to stderr.
- Duplicate cache mappings with the same target are idempotent. A duplicate with a different target is a hard error instead of silently overwriting history.
- Unsafe prefixes are rejected: absolute paths,
..,.gitcomponents, control characters, and leading-.prefixis interpreted relative to the repository root. ext::repository transports are rejected. Leading-repository arguments are rejected.- Progress is only rendered when stderr is a terminal.
splitworks in a bare repository;add,merge,pull, andpushstill require a work tree.split --rejoin --squashfollows current Git (2.36+) semantics: it synthesises a fresh squash commit as the second parent. The split tip itself is unchanged.split --rejoinwithout--squashmatches the old script.- A
git-subtree-splittrailer that is not a full object ID is never passed togit fetch. Fetching is limited to a validated OID, and the fetched object must resolve to a commit.
On a temporary clone of platform/applications (10,646 commits, 569 commits
touching app_db/agilicus-api, 3,056-commit split):
| Implementation | Cold split | Warm split | Max RSS | Split hash |
|---|---|---|---|---|
| pre-2.32 shell | 105.6 s | 105 s | 18.7 MB | 2df11996... |
| this tool (cold cache) | 1.9 s | 0.05 s | 118 MB | 2df11996... |
| this tool (warm cache) | n/a | 0.05 s | small | 2df11996... |
On platform/users (10,568 commits, prefix user_db_api/agilicus-api):
| Implementation | Cold split | Split hash |
|---|---|---|
| pre-2.32 shell | 104.7 s | a66b7d9f... |
| this tool | 1.55 s | a66b7d9f... |
The shell spends most of its time in fork/exec (one or more git processes per
commit). This tool uses one rev-list, one cat-file --batch, in-memory
ancestry, and native commit writing. The warm-cache path returns the recorded
tip immediately.
The vendored upstream t7900-subtree.sh suite passes all 73 tests (7 GPG tests
skip when no key is available). The integration tests in integration_test.go
also compare this implementation against the pre-2.32 reference script on
squash add, pull, split, rejoin, annotation, ignore-joins, and duplicate-cache
histories.
To run the upstream suite against the built binary:
make build
scripts/run-t7900.sh /path/to/git.gitThe script creates a temporary GIT_EXEC_PATH containing bin/git-subtree and
runs the upstream suite. All 73 tests pass, including the 7 GPG signing tests
when gpg is available. The Makefile's install-canary target creates a similar
environment for manual testing.
The cache lives under $GIT_COMMON_DIR/subtree-cache/v2/<key>.cache. It is an
append-only text log keyed by the prefix, annotation, resolved --onto,
--ignore-joins, object format, commit encoding, abbreviation setting, and
replace-ref state. Entries are immutable commit mappings; a missing object is
recomputed rather than trusted.
Disable it with:
GIT_SUBTREE_NO_CACHE=1 git subtree split --prefix=... HEADConcurrent writers use a per-key advisory lock; a second writer falls back to a run-local cache instead of corrupting the shared one.
Cache entries are advisory. Synthetic commits are unreferenced until you push or
branch them; an aggressive git gc --prune=now can remove them. If that
happens, remove .git/subtree-cache/v2 (or set GIT_SUBTREE_NO_CACHE=1) and
re-run the split. Normal Git GC grace periods make this a non-issue in practice.
GPL-2.0-only. The algorithm, test suite, and reference script come from git.git
contrib/subtree; upstream copyright notices are retained in
testdata/git-subtree.orig.