Skip to content

About

Drop-in Go replacement for git subtree

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

git-subtree-go

A drop-in replacement for git subtree, written in Go.

The goals are, in order:

  1. Compatible: the same commands, options, output conventions, and synthetic split commit IDs as contrib/subtree/git-subtree.sh.
  2. Secure: no shell, no eval, no word splitting, strict validation of prefixes, refs, revisions, repository arguments, and commit-message trailers.
  3. Reliable: idempotent cache entries, atomic object writes, transactional add, deterministic results, and clear errors.
  4. 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.

Status

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-tree fallback for signed or unusual commits
  • strict prefix/ref/revision/repository validation
  • OID-only trailer fetching (a malicious git-subtree-split refspec cannot create or update local refs)

Build and test

make build
make test
make test-race

Install the standard hooks once per clone:

pre-commit install --hook-type commit-msg --hook-type pre-push
pre-commit run --all-files

The 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.

Install

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-go

Usage

Exactly 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.

Compatibility notes

  • 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, .., .git components, control characters, and leading -. prefix is 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.
  • split works in a bare repository; add, merge, pull, and push still require a work tree.
  • split --rejoin --squash follows current Git (2.36+) semantics: it synthesises a fresh squash commit as the second parent. The split tip itself is unchanged. split --rejoin without --squash matches the old script.
  • A git-subtree-split trailer that is not a full object ID is never passed to git fetch. Fetching is limited to a validated OID, and the fetched object must resolve to a commit.

Measured performance

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.

Conformance

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.git

The 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.

Cache

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=... HEAD

Concurrent 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.

License

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.

About

Drop-in Go replacement for git subtree

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages