ADR 0014: git runs on isomorphic-git, fetched and verified on first use
- Status: accepted (2026-10-21)
- Context:
git is one of the v1 shell commands, planned to run on isomorphic-git or
an equivalent. Agents use git to checkpoint work, diff their changes, and branch experiments.
isomorphic-git (MIT) is a pure-JavaScript implementation that reads and writes real git
repositories. Its package is about 1.2 MB as a tarball and 5 MB unpacked. Bundling it into the
shell would add a runtime dependency to a core package (core packages avoid runtime dependencies) and grow every process worker.
- Decision:
git is a shell command (packages/shell/src/commands/git.ts). On first use it downloads
the pinned release isomorphic-git@1.44.3 from the registry, checks its SHA-512 integrity,
and unpacks it into /usr/local/lib/clientvm/isomorphic-git@1.44.3, reusing npm’s installer
(ADR 0012). The bundle is evaluated with Node’s Buffer in scope; the command adapts the
shell’s synchronous filesystem to isomorphic-git’s promise API.
- The command implements git’s porcelain on top of isomorphic-git’s plumbing and matches real
git’s output.
test/e2e/git.spec.ts runs the same steps under ClientVM and the host’s git
with fixed dates and compares stdout, exit codes and commit ids.
- Where isomorphic-git lacks a feature that git’s porcelain needs, the command fills it in:
log walks history in git’s date order.
- Merge conflicts leave
MERGE_HEAD, MERGE_MSG and conflict markers labelled HEAD, and
the next commit records both parents. isomorphic-git’s index has no conflict stages, so
unmerged paths are listed in .git/clientvm-unmerged until git add resolves them.
- Remote operations use
fetch. Most git hosts do not send CORS headers, so clone, fetch,
pull and push need a CORS proxy (GIT_CORS_PROXY). ClientVM has no server-side component
and does not provide one.
- Consequences:
- The first
git call in an instance costs one registry download (about 1.2 MB); later calls
load the unpacked copy. Upgrading means changing the version and integrity constants and
re-running git.spec.ts.
- Not supported: an editor (
commit needs -m/-F), rebase, cherry-pick, blame, hooks,
submodules, .gitattributes, rename detection.
.git/clientvm-unmerged is not a real git file. Real git ignores it, and an interrupted
merge must be finished in ClientVM.
Edit this page on GitHub ↗Markdown