git-cross is a small tool for pulling part of one Git repository into another and keeping it as real files in your tree — no submodule, no gitlink, no copying step.
It is for the cases where you want real files in your tree, not a gitlink, and want a simple way to refresh them from upstream.
git-cross is useful when you want to:
- vendor only one subdirectory from another repository
- keep vendored code as normal files in your own repository
- pull upstream updates without converting your repo into a submodule setup
- manually compare your local edits with the upstream state when both have changed
- let AI tools work on a mounted subfolder instead of your full repository
Compared with submodules or subrepo-style flows, the tradeoff is simple: git-cross keeps files physical and visible in your repo, and tracks the upstream relationship separately through a per-cross gitdir and Crossfile.
- Pull
docs/from an upstream project intovendor/docs - Keep a shared app template in
vendor/templateand customize it locally - Work on an upstream library inside
vendor/libwith normal editor tooling - Let an AI sandbox mount only
vendor/libinstead of the whole repo - Publish your local combined result to your own
origin
Version 0.5.3 — the current release (0.5.1/0.5.2 were the breaking scope
split: Go is the only full implementation, the Just/Fish reference carries core
commands only, Rust was deleted; plus the ls DIFF and crossed-dir recognition
fixes). The 0.5.0 architecture underneath is unchanged: crosses are
a standalone gitdir per cross with the work tree inside your repo — no
migration path; .cross/ is disposable (rm -rf .cross && git cross update).
See CHANGELOG.md.
The repository supports two implementations (no longer 1:1 since v0.5.1):
- Go — the primary and ONLY full implementation: every command, production use
- Just/Fish — a CORE-only reference (
use,set,del,ls,cfg/initand the git passthrough) for prototyping and as a readable code showcase;update,resolve,wipe,comp,shell-init,cdandwtanswerNOT IMPLEMENTED in Justfile versionthere
The Rust implementation was deleted from the repository (v0.5.1). For normal usage, prefer the Go binary.
just installManual build (remove a stale vendor dir first; -mod=mod for the module path):
cd src-go && rm -rf vendor
CGO_ENABLED=0 go build -mod=mod -o git-cross-go main.go
git config --global alias.cross "!$(pwd)/src-go/git-cross-go"just install shell# 1. Register upstream
git cross use demo https://github.com/example/demo.git
# 2. Materialize one directory locally
git cross set demo:docs vendor/docs
# 3. Commit the vendored files in YOUR repo (they are normal files)
git add vendor/docs && git commit -m "vendor: docs"
# 4. Inspect local state
git cross ls # crosses + health (DIFF, upstream SHA)
cd vendor/docs && git cross diff # upstream-context diff (your edits vs upstream)
# 5. Later: fetch upstream, land it, and re-apply your changes
git cross update vendor/docs
# collision? resolve it in your repo, then:
git cross resolve --continuegit-cross connects four things:
- Your main repository (the patched files are tracked by it as normal files)
- A standalone bare gitdir per patch under
.cross/worktrees/<remote>/<patch>/holding the upstream.gitcontent (objects, refs, remotes, sparse config, rerere) - A crossed directory such as
vendor/docs— this is the upstream work tree - A
Crossfilethat records how to rebuild the setup
On disk:
your-repo/
├── Crossfile # declarative use/set records
├── .cross/ # disposable state (gitignored)
│ ├── metadata.json # local_path + worktree + gitdir + branch + remote_url
│ └── worktrees/
│ └── <remote>/<patch>/ # BARE gitdir: HEAD, config, objects/, info/sparse-checkout
└── vendor/docs/ # THE WORK TREE: plain files, no .git, tracked by your repo
There is no .git file in the crossed directory, no linked worktree, and no rsync:
the work tree lives in your repository, and the upstream .git content lives in
.cross/.
The crossed directory has no .git of its own, so the same files belong
to two repositories at once — which one you talk to depends on how you invoke
git:
You run (inside vendor/docs) |
git operates on | Why |
|---|---|---|
git status |
your repository | no .git in the crossed dir → git walks up to your repo root |
git cross status |
upstream repository | git-cross runs git with GIT_DIR=<gitdir> + GIT_WORK_TREE=<crossed dir> |
That is the whole mechanism. git cross <git-cmd> is plain git with two
environment variables set for the child process:
GIT_DIR=.cross/worktrees/<remote>/<patch> # the bare upstream gitdir
GIT_WORK_TREE=<repo>/<local_path> # the crossed directory
Or as a shell function — this is essentially all git cross is inside a
crossed directory:
xup() { # "upstream git": git cross <cmd> inside vendor/docs, minus the bookkeeping
GIT_DIR="$repo/.cross/worktrees/demo/vendor_docs" # the hidden upstream gitdir
GIT_WORK_TREE="$repo/vendor/docs" # the crossed directory
exec git "$@"
}To git it looks exactly like standing in a normal clone of upstream whose
working tree is vendor/docs: status, diff, log, add, push,
pull -r all operate on upstream, while your own repo keeps tracking the
same files as plain blobs. No second checkout exists — the crossed directory
is the upstream work tree.
Both repositories keep independent histories over the same files, and nothing is auto-synced between them:
git cross add+git cross commit(+git cross push) lands the change in upstream — your repo still shows the file as modified until you commit it there too, with plaingit.git cross pull -r(orgit cross updatefrom anywhere in your repo) changes the files on disk — your repo simply sees them as changes to commit.
git cross set demo:docs vendor/docs performs that whole setup in one
command. Stripped of the bookkeeping it is:
gd=.cross/worktrees/demo/vendor_docs # 1. hidden home for upstream's .git
git clone --bare https://github.com/example/demo.git "$gd" # (full clone by default;
git --git-dir="$gd" config core.sparseCheckout true # shallow/partial is opt-in:
echo 'docs/' > "$gd/info/sparse-checkout" # git config cross.depth 1)
GIT_DIR="$gd" GIT_WORK_TREE=vendor/docs \
git read-tree -mu HEAD # 2. materialize the work tree, as plain filesFetch-first, work-tree-second: the clone goes only into the hidden gitdir,
then the work tree is written into vendor/docs/. A .git file is never
created in the crossed directory — that is what makes your repo track the
files as normal blobs instead of a submodule.
A complete first cycle — register, materialize, edit, update (output captured from a real run):
$ git cross use demo https://github.com/example/demo.git
==> Remote demo registered (https://github.com/example/demo.git).
$ git cross set demo:docs vendor/docs
==> Autodetecting default branch...
==> Using branch: main
==> Setting cross demo:main:docs -> vendor/docs
==> Cloning upstream into .cross/worktrees/demo/vendor_docs (bare)...
Cloning into bare repository '.cross/worktrees/demo/vendor_docs'...
==> Cross set successfully.
$ ls vendor/docs/docs # the crossed dir mirrors the upstream ROOT
guide.md
$ git add vendor/docs # normal files — tracked by YOUR repo
$ git commit -m "vendor: demo docs"
$ echo "My local tweak." >> vendor/docs/docs/guide.md # edit with any tool
$ cd vendor/docs
$ git cross status # UPSTREAM context (GIT_DIR/GIT_WORK_TREE)
On branch main
Changes not staged for commit:
modified: docs/guide.md
no changes added to commit (use "git add" and/or "git commit -a")
$ git status --short # plain git, SAME directory: your repo
M docs/guide.md
$ git cross diff --stat # your edits vs upstream HEAD
docs/guide.md | 1 +Days later, upstream published something new:
$ git cross update # from anywhere in your repo
==> Updated vendor/docs
$ git cross ls
==> Configured crosses:
┌────────┬─────────────┬────────────┬────────────┬──────────────────────────────┬────────┬───────┬────────┐
│ REMOTE │ REMOTE PATH │ LOCAL PATH │ WORKTREE │ GITDIR │ BRANCH │ DIFF │ SHA │
├────────┼─────────────┼────────────┼────────────┼──────────────────────────────┼────────┼───────┼────────┤
│ demo │ docs │ vendor/docs │ vendor/docs │ .cross/worktrees/demo/vendor_docs │ main │ Clean │ c0448a9 │
└────────┴─────────────┴────────────┴────────────┴────────────────────────────┴────────┴───────┴────────┘
$ git status --short # upstream landed, staged, in YOUR repo
A vendor/docs/docs/extra.mdupdate refuses to run over unstaged edits under the crossed path
(==> WARNING: 'vendor/docs' has modified files; commit them in your repo first),
and a collision is kept as conflict markers you finish with
git cross resolve. Cross never commits for you.
In practice:
- your editor,
git add, and CI see normal files - AI tools can work on normal files
- upstream git operations run in the cross's own context:
cd vendor/docs && git cross status | log | diff | push | pull -r - plain
gitstill means your repository (that is how you commit patched files) Crossfilerecords theuseandsetdeclarations;git cross updatereads them
Two docs hold the decisions:
specs/003-gitdir-patches/adr-001-metadata-locations.md (location fields) and
adr-002-passthrough-requires-patch.md (the passthrough needs a patch context).
Why a standalone bare gitdir per cross instead of one clone of upstream plus
git worktree add? The deciding constraint is the core feature:
The crossed directory must contain no
.git— only then does the primary repo track the patched files as normal blobs instead of a gitlink/submodule.
Every alternative that puts .git (or a .git file) into the crossed directory
is disqualified by that one rule:
| Approach | .git in crossed dir? |
Files tracked by your repo | Isolation |
|---|---|---|---|
| submodule | yes (its own) | no — gitlink, not blobs | separate repo, init/update dance |
full clone in vendor/x |
yes | no — nested repo/gitlink | independent, but never your blobs |
linked git worktree |
yes (.git file) |
no — nested repo/gitlink | bound to a full clone of upstream + shared refs |
| git-cross bare gitdir | no | yes — plain blobs | fully standalone gitdir |
A linked git worktree also needs a full clone of upstream somewhere inside
your repo and couples every cross to that clone: one shared object store and one
shared refs namespace mean two crosses from the same upstream fight over branch
state, and deleting the main clone orphans the worktrees.
What the gitdir-per-cross design gives up is shared object storage: each cross
keeps its own copy of upstream objects. In exchange every cross is an island —
own objects, own refs, own rerere — which is exactly what enables:
- the same upstream patched into several local directories with different
branches, each pair fully independent (
.cross/worktrees/<remote>/<patch>/) - different upstream repos side by side (one gitdir per cross, trivially)
.cross/being disposable:rm -rf .cross && git cross updaterebuilds every cross fromCrossfile
Disk duplication is the whole trade-off, and it is opt-in mitigable:
git config cross.depth 1 / cross.filter blob:none shrink each gitdir.
The sparse checkout config inside each gitdir is the filter that decides which
upstream subtree gets materialized into the work tree (set demo:docs …
checks out only docs/, whole-repo crosses get everything).
git-cross enables Git's rerere ("reuse recorded resolution") so that
conflict resolutions survive across updates — you resolve the same update
conflict once, not every time:
git cross cfg(or theinitalias) turnsrerere.enabledon and tells you so.git cross setenables it silently in the cross's own gitdir.git cross updatere-ensures it on both sides, so older setups self-heal.
The usual conflicting-update loop — update itself replays what it remembers:
git cross update # fetch + land + re-apply; conflict stays in your repo
# ... edit the marked files ...
git add <files>
git cross resolve --continue # then commit
git commit -m "vendor: resolve upstream"The manual alternative, when you want to drive the upstream side yourself:
cd vendor/app # the crossed directory IS the upstream work tree
git cross pull -r # fetch + rebase against upstream
git cross add <file>
git cross rebase --continueEither way Git records the resolution; when the same conflict reappears, the next
apply replays it (Resolved '<file>' using previous resolution).
Notes:
- The setting lives in two places: your repository's config (the patched files are tracked by it) and every cross gitdir. A cross gitdir is a standalone repository — it does not inherit your config.
- Recorded resolutions are per-repository:
update/resolverecord and replay in your repo (<repo>/.git/rr-cache), while the manualpull -rflow records in the cross gitdir. Each cross therefore has its own conflict memory on both sides. rerere.autoUpdateis deliberately not enabled. Replayed resolutions are applied to the working tree but not staged, so a rebase still stops forgit add+ continue. Opt in withgit config rerere.autoUpdate true.git cross updateis where rerere pays off: the re-apply is a real three-way apply in your repo, so a conflict you already resolved is replayed instead of asked again.
The common pattern is local-only files next to upstream-managed ones:
git cross use app https://github.com/example/app.git
git cross set app:src vendor/app
echo "API_KEY=..." > vendor/app/.env # local-only, next to upstream filesv0.5.0 removed .crossignore (the v0.4 status/diff override filter). Local
extra files are simply untracked-by-upstream files in the crossed directory:
- they never affect
git cross update(only tracked upstream paths are applied), - they do not appear in the cross's upstream-context
git cross diff(git diffshows tracked changes only), - they will appear in
git statusof your repository, exactly like any other new file you did not commit — add them to your.gitignore(or commit them deliberately) if that matters.
If you keep secrets or machine-local files in a crossed directory, review them explicitly before publishing.
There are two separate publish flows.
This is just normal Git in your main repository:
git add vendor/app
git commit -m "Update vendored app and local overlays"
git push origin mainYour own repository stores the final combined result, including local overlay files if you choose to commit them there.
The crossed directory is the upstream work tree, so contributing is just git in the crossed-directory context:
xcd vendor/app # or: gx cd vendor/app (see shell integration)
git cross diff # line diff of your copy against upstream HEAD
git cross status # git status IN THE UPSTREAM context (plain `git` = YOUR repo)
git cross add -p # stage just your fixes
git cross commit -m "fix: ..."
git cross push # pushes to the PATCH's upstream, not your repogit cross status here is the passthrough — plain git status run with the
cross's GIT_DIR/GIT_WORK_TREE. The cross overview (with DIFF + upstream
SHA) is git cross ls, runnable from anywhere in the repo.
Recommended pattern:
cdinto the crossed directory (xcd vendor/app).git cross difffor a line diff against upstreamHEAD.- Stage and commit only the upstream-worthy changes, then
git cross push. - Keep the rest as your local result: commit it in your own repository with
plain
git add/git commit(the files are normal repo files).
Directory-level comparison is no longer a cross command: the crossed directory is
already the upstream work tree, so git cross diff / --stat is the natural
view. See Directory Comparison.
- Overview
- Tutorial: Local Overlays And Upstream Contribution
- Tutorial: Whole Upstream Into A Local Directory
- Tutorial: Migrate A Private Fork To git-cross
- Tutorial: Split One Repo Into A Clean Upstream And A Private Overlay
- Sandbox Kits
git cross --help groups commands by intent (Go CLI):
Crossed paths/dir operations:
use Register an upstream remote in metadata (your git remotes are not touched)
set Set a cross directory: vendor an upstream path into your repo (bare gitdir + in-repo work tree)
del Delete a cross: gitdir + crossed dir + Crossfile/metadata entries
cfg Configure the repo for git-cross: Crossfile + rerere + .gitignore (init kept as alias)
update Fetch upstream and land it in the crossed dir, re-applying your changes
resolve Finish an update conflict: report unmerged paths, or continue/abort
git cross overview:
ls Show all configured remotes and crosses (with DIFF + upstream SHA)
comp Print shell completions + wrappers (xcd, gx, cr) to evaluate
wipe Remove unused remotes (metadata + gitdirs), or all crosses of a specific remote
help Help about any command
Cross never shadows native git. Any command name that is not a cross command
falls through to the passthrough: git cross status, git cross log,
git cross push, git cross pull -r run git in the cross's upstream context
when you are inside a crossed directory. Outside one they fail early with a hint —
they never silently operate on your own repository. Use plain git for that.
Running git cross with no subcommand does not print help. It prints one row
per configured cross to stdout:
$ git cross
vendor/app .cross/worktrees/app/vendor_app
vendor/lib .cross/worktrees/lib/vendor_lib
The listing is the machine-readable row format used throughout the tool:
when stdout is a terminal the first column is space-padded for readability;
when piped, rows stay local_path<TAB>gitdir so
git cross 2>/dev/null | cut -f1 yields local paths. ==> WARNING:/==> ERROR: lines and hints go to stderr
(status ==> lines stay on stdout, so pipes carry data only). Use git cross -h or git cross --help for the grouped
help shown above.
git cross use <name> <url>Register an upstream remote alias in .cross/metadata.json (and Crossfile).
The URL is verified as reachable. Your repository's git remotes are not
touched — upstream remotes live in each cross's gitdir.
git cross set <remote>:<branch>:<path> [local_dest]Clone the upstream .git content into a standalone bare gitdir at
.cross/worktrees/<remote>/<local_dest>/, sparse-filter <path>, and materialize
the work tree in place at local_dest (no copy step).
<path> mirrors the upstream root: setting app:src into vendor/app puts the
files at vendor/app/src/... (the crossed directory is a checkout of the upstream
repo, restricted to that path). Whole-repo crosses (app:. or app:/) get
Everything.
Every cross owns its own gitdir, so the same upstream source set into several local directories is fully independent:
git cross set app:src vendor/app
git cross set app:src vendor/app-copy # separate gitdir, separate work treeset never overwrites silently: when local_dest exists but is not
registered, it refuses with a hint (refusing to overwrite it (add it to Crossfile and run: git cross update --force — or remove the directory)). The
hint names both remedies because update only walks Crossfile: without a
set line, --force has nothing to adopt.
Opt in to a smaller clone:
git config cross.depth 1 # shallow
git config cross.filter blob:none # partial (blobless)git cross update [path] [--no-resolve] [--force]Two phases, in this order:
- Fetch every patch into its mirror (
.cross/worktrees/<remote>/<patch>/). Fetching is innocent: it only writesrefs/remotes/origin/<branch>, never a work tree. - Land upstream and re-apply your version in your repo:
- unstaged changes under the crossed path → refuse
(
'<path>' has modified files; commit them in your repo first). Only unstaged edits can be lost: the apply merges into your index, so staged content (e.g. filessetjust added) is safe. - pending conflict under the crossed path → skip and tell you to run
git cross resolve. - otherwise: upstream lands in the crossed directory and your committed changes
are re-applied on top, in one three-way apply. Clean → the merged result is
staged, report
Updated <path>, and the mirror follows. Collision → kept: conflict markers plus unmerged paths in your repo, andrerererecords/replays the resolution (.git/rr-cache). --no-resolvelands upstream as-is (upstream wins every collision, no markers); your version stays in your history for a latergit cross resolve.--resolveis accepted for symmetry with--no-resolve(it is the default, and hidden from--help).
- unstaged changes under the crossed path → refuse
(
Lost .cross state. When a crossed directory exists but its registration
is gone — the whole .cross/ deleted, or only its gitdir — update will not
silently overwrite your files:
- Go (primary) asks:
Delete '/abs/path' and re-adopt it from upstream? [y/N]:. The default is No (empty/EOF input),yadopts: the directory is wiped and re-created from upstream (Re-adopting <path> from upstream (existing dir wiped)). Declined crosses are skipped untouched and counted in a summary warning (<n> cross(es) not adopted: not confirmed (use --force to adopt without asking).).--forceauto-applies the yes — no prompt. - Just/Fish (reference) is non-interactive: plain
updaterefuses with a hint (use --force to re-adopt it from upstream);update --forceadopts the same way as Go (wipe + re-create from upstream).
--force also covers the gitdir-only case (registration intact, gitdir lost):
the stale registration is dropped first and the cross is re-set from upstream.
Re-adoption deletes a directory, so both implementations guard the wipe before it happens:
- Uncommitted edits block the wipe. Before deleting, the crossed dir is
checked with
git status --porcelain -- <path>; anything staged or unstaged (a modified tracked file, a new untracked file) refuses the run:<path> has uncommitted changes; commit or stash them first (refusing to delete them)(Go:Error: …, exit 1; Just/Fish:==> ERROR: …, exit 1).--forcedoes not override this: a wipe is irreversible and lost.crossstate leaves cross nothing to replay your edits from, so it refuses instead of guessing. Commit or stash the work, or delete the directory yourself. - Declined vs aborted: when you decline the prompt, Go skips that cross and continues with the summary warning (other crosses still update); Just/Fish aborts the whole run with exit 1, so no cross is updated.
--forceon a healthy registered cross is a no-op — it only appears in the lost-state branches and never wipes a registered cross.git cross update <path>with a declined prompt reports the skip (<n> cross(es) not adopted: …) and exits 0; the hard errorno Crossfile cross found for path: <path>is reserved for paths genuinely absent fromCrossfile.
Cross never commits for you: after a clean update you commit the staged result as
usual (git add / git commit).
git cross resolve [path] # list what is left
git cross resolve --continue [path] # verify resolved, let the mirror follow
git cross resolve --abort [path] # crossed dir back to HEAD (upstream stays fetched)Resolution is ordinary git in your repo: edit the marked files, git add them,
git commit. resolve only reports, gates, and cleans up; it never invents merge
logic and never commits. --continue refuses while git ls-files -u still lists
paths under the patch.
Because the apply is one three-way diff of BASE..THEIRS against your HEAD,
thirty local changes cost one resolution round, not thirty — the upstream side is
what gets squashed, not your commits.
git cross ls [--raw] [--no-header]Show configured remotes and crosses. Default output is a table with
Configured Remotes: / Configured crosses: banners and descriptive column
headers. The crosses table carries the health columns (the old stat):
DIFF — Clean, Modified, Missing Files, Missing GD — and SHA,
the short upstream commit the cross has checked out (per gitdir; no fetch).
--raw switches to machine-readable output: no table borders and no banners.
When stdout is a terminal, columns are space-padded so they line up; when
piped, rows are plain TAB-separated values. --no-header omits the header
line in both table and raw mode. In raw mode the section order is fixed — all
remotes first, then all patches:
REMOTE_NAME REMOTE_URL
REMOTE REMOTE_PATH LOCAL_PATH WORKTREE GITDIR BRANCH DIFF SHA
LOCAL_PATH is the user-facing key, WORKTREE the crossed directory git operates
on (equal to LOCAL_PATH in 0.5.0), and GITDIR the bare upstream repository
under .cross/worktrees/. Remote rows are sorted by name. In pipes, header rows
are themselves tab-separated, so use --no-header in pipelines.
Parsing examples:
# Local paths only (patch rows have 6 fields, remote rows have 2)
git cross ls --raw --no-header | awk -F'\t' 'NF == 8 { print $3 }'
# Worktree (patch) directories
git cross ls --raw --no-header | awk -F'\t' 'NF == 8 { print $4 }'
# Bare gitdirs (upstream .git content)
git cross ls --raw --no-header | awk -F'\t' 'NF == 8 { print $5 }'
# "<remote>:<branch>" for every patch
git cross ls --raw --no-header | awk -F'\t' 'NF == 8 { print $1 ":" $6 }'
# Remote URLs
git cross ls --raw --no-header | awk -F'\t' 'NF == 2 { print $2 }'A plain cut works on the patch rows, but leaves blank lines for the
two-column remote rows:
git cross ls --raw --no-header | cut -f3 | sed '/^$/d'When nothing is configured, raw mode writes the empty-state message to stderr so stdout stays a clean pipe.
git cross del <path>Remove one patch: its gitdir, the crossed directory (a visible deletion in your
repository), the Crossfile line, and the metadata entry.
git cross wipe [remote]git cross wipe <remote>removes the remote record, every cross of that remote, and the remote's gitdir directory.git cross wipe(no argument) offers to remove remotes that no cross uses, then sweeps orphaned gitdirs that metadata does not reference.
v0.4 called this
prune, 0.5.0purge; nowwipe.git cross pruneandgit cross purgefall through to the git passthrough.
cd (hidden from help)
git cross cd [path]Print the absolute crossed directory — the only thing written to stdout (hints
and errors go to stderr). Run directly, the command only prints a path: a child
process cannot change your shell, which is why cd/wt are hidden from
git cross --help. The real directory change lives in the wrappers:
xcd [path] and gx cd [path].
wt [path] is a hidden alias of cd (kept from <=0.5.0, where it was the
upstream git passthrough — that role now lives only on the bare
git cross <git-args> fall-through).
A child process cannot change the working directory of the shell that started
it — no CLI can. Tools that appear to do it (yazi, zoxide, autojump) all use
the same pattern: the program prints the destination, and a small shell
function captures it and runs cd in your shell. git cross comp
prints that function pair together with the completion script:
# fish (~/.config/fish/config.fish, or a file in ~/.config/fish/functions/)
git cross comp fish | source
# shell auto-detected from $SHELL:
git cross comp | source# bash / zsh (~/.bashrc, ~/.zshrc)
eval "$(git cross comp)"
# or force a shell:
eval "$(git cross comp bash)"That defines these functions, which take the same optional path (and fzf
selection) as the commands themselves:
xcd vendor/app # cd into the crossed directory
gx cd vendor/app # same — gx is a shell function, so it CAN cd
gx add ./file # short alias for git cross
cr log --oneline # short alias for git crossgit cross cfg (alias: git cross init) prints the matching one-liner for your
$SHELL when it creates a Crossfile. For an even shorter git-level alias:
git config --global alias.x '!git cross' # then: git x add ./filePrefer to install the wrappers by hand? Copy the function into your shell's function directory (fish) or profile (bash/zsh); they are plain wrappers, not special builtins:
# ~/.config/fish/functions/gx.fish
function gx --description 'short alias for git cross (gx cd changes directory)'
if begin; test (count $argv) -ge 1; and test $argv[1] = cd; end
set -l rest $argv
set -e rest[1]
xcd $rest
else
git cross $argv
end
end# ~/.bashrc / ~/.zshrc
xcd() { local p; p="$(git cross cd "$@")" || return; [ -n "$p" ] && cd "$p"; }
gx() { if [ "$1" = "cd" ]; then shift; xcd "$@"; else git cross "$@"; fi; }xcd is already the short, idiomatic name — x as cross (like git x and
gx), so xcd reads as "cross cd". No further aliasing is needed; if the
name ever collides with something in your shell, wrap it instead of renaming
it (my-xcd() { xcd "$@"; }).
Keeping stdout path-only is deliberate: it makes the output composable in
scripts (dir=$(git cross cd vendor/app)) and safe to capture in a function.
With an explicit path the patch is resolved directly. Without one, fzf is
used to select a patch. The picker puts LOCAL_PATH first, then
REMOTE:REMOTE_PATH, and appends the branch in parentheses only when it is not
main; columns are padded so long remote names cannot run into the next field:
vendor/mxcsrc mxc-library:src
vendor/mxcpkg mxc-library:pkg (feature)
vendor/docs-src docs:src
3/3
──────────────────────────────────────────────
LOCAL_PATH REMOTE:REMOTE_PATH
Select patch>
If fzf is not installed, the command prints the available patch rows plus a
hint to cd manually, and exits 1.
compare (and its cmp alias) was removed in 0.5.0. In v0.4 it diffed two
directories — a hidden worktree and your copy. In 0.5.0 the crossed directory is
the upstream work tree, so there is no second checkout: the comparison is a
normal upstream-context git diff.
cd vendor/app
git cross diff --stat # your changes vs upstream HEAD
git cross diff # the same as a line diff
git cross log --oneline -5 # upstream historyAgainst a different upstream revision, fetch it into the gitdir and diff two trees explicitly:
cd vendor/app
git cross fetch origin
git cross diff origin/main -- .cross.dirdifftool, its {left}/{right} placeholders, the built-in
nvim/vim DirDiff default, and the DIRDIFF_EXCLUDES / DIRDIFF_IGNORE
variables went with the command. A leftover setting is ignored — remove it with
git config --unset cross.dirdifftool.
removeandpurgeguard against deleting repository-root contents when a patch targets..- Whole-upstream patches (
remote:.andremote:/) are supported: no sparse filter is written and every upstream file is materialized. - Repository-root local targets (
local_path = ".") are not supported byupdate. - The git passthrough requires a crossed directory. Outside one it exits 1 instead of running git against your repository (ADR-002).
.cross/is disposable state. Deleting it and runninggit cross updaterebuilds every cross fromCrossfile.- The crossed directory is tracked by your repository.
git cross deltherefore shows up as a deletion in your working tree — review before committing. .crossignoreoverrides were removed in 0.5.0; local-only files simply stay untracked/ignored by your own.gitignore.updatenever overwrites your committed work: a collision is left as unmerged paths + markers in your repo. It does refuse to run over unstaged edits, so commit (or stash) before updating.- While a conflict is unresolved,
git add -Ain your repo would stage the markers. Resolve first, then stage:git cross resolvelists exactly what is left. update --no-resolvetakes upstream as-is (upstream wins every collision). Your version is not lost — it is still in your history — but the crossed dir no longer reflects it; re-rungit cross resolveafter restoring what you want.
This repo already includes agent guidance for AI coding tools:
- shared repo roles in
.agents/ - Claude-facing entrypoints in
.claude/ - OpenCode-native skills in
.opencode/skills/
Current shared roles:
- maintainer
- feature spec writer
- safety reviewer
- regression tester
If you want an AI agent to work only on a vendored subtree, mount just that subtree in a sandbox and keep the main .git state on the host.
This repo includes repo-local starter kits under sbx-kits/.
Examples:
sbx run opencode --kit ./sbx-kits/opencode
sbx run claude --kit ./sbx-kits/claudeWhy use a kit:
- safer trial path for people who do not want to install a new tool globally first
- reproducible sandbox setup checked into the repository
- easy place to add sandbox-local agent config later
See sbx-kits/README.md for the structure, starter kits, and intended workflow.
High level:
- One bare gitdir per patch under
.cross/worktrees/<remote>/<patch>/holds the upstream.gitcontent (objects, refs, remotes, sparse config, rerere). - The work tree is the crossed directory inside your repository — plain files,
tracked by your repo, no
.gitpointer, no rsync. - Upstream git runs through
GIT_DIR/GIT_WORK_TREE— the baregit cross <git-args>fall-through, only from inside a crossed directory (cd/wt are hidden path-printers). .cross/metadata.jsonrecordslocal_path,worktree,gitdir,branchandremote_url(ADR-001).- Go is the primary and only full implementation; Just/Fish is the core-only
prototyping reference (Go-only commands are
NOT IMPLEMENTEDstubs there). Rust was deleted (v0.5.1).
Decisions: specs/003-gitdir-patches/adr-001-metadata-locations.md,
adr-002-passthrough-requires-patch.md. Design notes: docs/overview.md.
MIT