git-orchard
A command-line utility for managing git-subtrees.
Install
AUR:
git-orchard is available from the Arch User Repository.
yay -S git-orchard
pip:
git-orchard is available as a pypi package.
pip install git-orchard
go:
go install github.com/jmelahman/git-orchard@latest
Usage
Subtrees are listed in a committed manifest at the repository root, .gitsubtrees or .config/git-orchard/subtrees (but not both), in the same syntax as .gitmodules:
[subtree "tools/foo"]
remote = git@github.com:owner/foo.git
branch = master
The same keys in git's own configuration (e.g. .git/config) override it for one clone.
Pulls and adds are squashed unless the manifest sets orchard.squash = false.
git orchard init # list the subtrees already in git history
git orchard add tools/foo git@github.com:owner/foo.git
git orchard status # commits ahead/behind each upstream
git orchard pull [prefix...] # merge upstream changes
git orchard push [prefix...] # publish, fast-forward only
git orchard push --changed-since REV # only subtrees changed since REV
git orchard push --tag tools/foo/v1.2.3 # publish as v1.2.3 upstream
git orchard release tools/foo # tag the next version, e.g. tools/foo/v1.2.4, and push it to origin
git orchard release tools/foo v2.0.0 # or a version of your choosing
git orchard sync [prefix...] # copy shared files into subtrees
Without a version, release picks one after the latest release, much as tag does: the patch version incremented (--minor and --major increment those instead), or a pre-release's stable release; --suffix rc picks the next release candidate, e.g. v1.2.4-rc, then v1.2.4-rc.1.
Releases are the <prefix>/v* tags in the monorepo and on its remote, and the v* tags upstream, so releases from before the subtree count; --dry-run prints the pick.
release requires the upstream branch to contain the release already, so the upstream tag lands on its history; --upstream pushes the branch and tag there directly instead of leaving it to the action.
push, pull and release take --no-verify to skip git hooks.
push --force overwrites upstream branches and tags, leased on their value when the push starts so a concurrent update still fails it; the action never forces.
release --force moves an existing tag, unless the upstream already published it at another commit: the Go module proxy and release artifacts won't follow a moved release.
push splits each subtree out of the monorepo with git subtree split, which is deterministic, so the same history always gives the same commits and every push is a fast-forward.
An upstream with commits the monorepo doesn't have rejects the push until they're pulled in.
git-orchard only runs git, so credentials, SSH config and url.<base>.insteadOf rewrites apply as usual.
Shared files
Subtrees that are published on their own each need their own copy of config like .pre-commit-config.yaml or .github/dependabot.yml.
git orchard sync keeps those copies in step with one source.
A subtree lists the profiles it shares, and each profile is a directory under orchard.sharedDir (.config/git-orchard/shared by default):
[subtree "tools/foo"]
remote = git@github.com:owner/foo.git
shared = base
shared = go
.config/git-orchard/shared/
base/.github/dependabot.yml # → tools/foo/.github/dependabot.yml
base/.pre-commit-config.yaml
go/.pre-commit-config.yaml
A file in a profile lands at the same path in the subtree, replacing it whole. When the subtree's file marks a block for the profile, only the lines between the markers are replaced, and the rest of the file stays the subtree's own:
repos:
# BEGIN orchard:base
# END orchard:base
# BEGIN orchard:go
# END orchard:go
- repo: local # not shared
hooks: [...]
Markers work in any comment syntax, since git-orchard only looks for BEGIN orchard:<profile> and END orchard:<profile> in the line.
Two profiles can share a file only through blocks.
sync exits 1 when it changes a file, like a formatter, and --check prints the differences without writing them.
To run it on every commit, add the hook to the monorepo's root pre-commit config (not to the subtrees', since their mirrors have no manifest):
repos:
- repo: https://github.com/jmelahman/git-orchard
rev: v1.2.3
hooks:
- id: git-orchard-sync
GitHub Action
This repository is also an action that mirrors a monorepo's subtrees on every push: changed subtrees are pushed to their upstreams, and a <prefix>/<name> tag is published to that prefix's upstream as <name>.
on:
push:
branches: [master]
tags: ["**/v*"] # `*` doesn't match `/`
jobs:
mirror:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0 # splits need the full history
persist-credentials: false
- uses: jmelahman/git-orchard@v1
with:
app-client-id: ${{ vars.ORCHARD_APP_CLIENT_ID }}
app-private-key: ${{ secrets.ORCHARD_APP_PRIVATE_KEY }}
The action pushes as a GitHub App, which git orchard github-app creates:
git orchard github-app # add --org ORG for an organization's repositories
It opens a browser to create a private App under your account from a manifest (contents and workflows write, no webhook), then to install it: pick the upstream repositories there.
With the GitHub CLI installed, it stores the App's client ID and private key on the monorepo (origin, or --repo) as the ORCHARD_APP_CLIENT_ID variable and ORCHARD_APP_PRIVATE_KEY secret; otherwise it writes the key to a file and prints the gh commands to store it.
The App and its key are yours; git-orchard runs no service.
The action mints a short-lived token from the App's installation for owner (default: the monorepo's owner).
Alternatively, pass token, e.g. a fine-grained token with "Contents" and "Workflows" read and write on the upstreams; GitHub refuses pushes that change .github/workflows without the latter.
Either way, GitHub remotes in the manifest are rewritten to use the token.
changed-since defaults to the start of the pushed range; set it empty to push every subtree.
The action builds git-orchard from its own source, so the CLI is always the version the action is pinned to.
Metadata
Release files for git-orchard 1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| git_orchard-1-py3-none-manylinux_2_17_x86_64.whl | Python 3 | none | Linux glibc 2.17+ x86-64 | Details for git_orchard-1-py3-none-manylinux_2_17_x86_64.whl |
| git_orchard-1-py3-none-manylinux_2_17_aarch64.whl | Python 3 | none | Linux glibc 2.17+ ARM64 | Details for git_orchard-1-py3-none-manylinux_2_17_aarch64.whl |
Total release size: 8.2 MB
Release files / git_orchard-1-py3-none-manylinux_2_17_x86_64.whl
| Download URL | git_orchard-1-py3-none-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 4.3 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
40fff2cf2d1eb01b83fb06453d52ed2b115e4c441ab619505822e435c4459221
|
|
BLAKE2b-256 checksum How to use checksums |
e4dbd2fb2c4abd40f69b401a1b145a014defecf4b179505a5cc8cab9a50d3ce6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / git_orchard-1-py3-none-manylinux_2_17_aarch64.whl
| Download URL | git_orchard-1-py3-none-manylinux_2_17_aarch64.whl |
|---|---|
| Size | 3.9 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
9d3226574af7c4be9745f57789456c304ef1af30d9d7d8c25608b8825de18313
|
|
BLAKE2b-256 checksum How to use checksums |
6c65f8243a6970b9d1dc36b234428368d2cdc073c745078e254f14c3218dd0a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for git-orchard 1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.