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 [email protected] from the registry, checks its SHA-512 integrity, and unpacks it into /usr/local/lib/clientvm/[email protected], 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