Skip to content

0019: The git backend shells out to git

  • Status: accepted
  • Date: 2026-09-25
  • Amended by: 0041 (hooks do not run on vault-branch commits)

Context

The git backend (core/store/gitstore, built in group 1 of the implement-cli-v1 change) has to commit vault files, fetch, merge and push against whatever remote the user already uses: GitHub, GitLab, a self-hosted forge or a bare repository over SSH. Users reach those remotes through configuration that lives outside vaultfold: credential helpers, the SSH agent and ~/.ssh/config (ProxyJump, IdentityFile, hardware keys, 1Password's agent), includeIf, insteadOf rewrites, proxies, commit signing (commit.gpgsign, SSH signing), hooks and safe.directory. Teams that require signed commits by branch protection need vaultfold's commits signed too.

At the same time the storage-backends spec requires sync never to rebase, force-push or rewrite a published commit, and ADR 0004 makes every vault write a new, content-addressed file, so a correct merge only ever adds files. User configuration such as merge.ff=only, pull.rebase=true or rebase.autoStash=true must not be able to change that.

Decision

gitstore runs the user's own git binary (2.30 or newer) through os/exec instead of linking a Go git library. This rests on the implement-cli-v1 design.md sections "Git access: shell out to the git binary" and "Git backend (core/store/gitstore)", and on "Decisions taken during group 1", including the two items it marked ADR-pending, which this record closes.

Invocation hygiene, applied to every call:

  • exec.CommandContext with an argument vector, never a shell; paths are passed after a literal --.
  • A fixed environment: LC_ALL=C (output parsing never depends on the locale), GIT_LITERAL_PATHSPECS=1 (a path with :, *, ? or [ is never read as pathspec magic; group 1 decision 5), GIT_TERMINAL_PROMPT=0 when there is no terminal (CI fails fast rather than hanging on a credential prompt), GIT_OPTIONAL_LOCKS=0 for read-only commands. Porcelain and -z output formats only.
  • Configuration that would break the invariants is pinned per call with -c: merge --no-edit --ff with merge.renames=false, merge.autoStash=false and rerere.enabled=false (group 1 decision 4). pull is never used, so pull.rebase never applies.
  • The binary is resolved with exec.LookPath when a repository is opened, and its version is checked on every open (ErrGitTooOld, exit 4).
  • The user's commit identity is used; only when user.name and user.email are both unset does gitstore supply a default identity with -c. Signing follows the user's configuration, and a signing failure is reported verbatim (exit 4).
  • Hooks run, so the user's policy applies to vaultfold's commits; the vaultfold pre-commit hook recognises a commit that stages only vault files as clean. A hook or signing failure unstages what Commit staged (group 1 decision 6).

Adds-only merges:

  • Commit stages only the named vault paths and runs git commit --only, so anything else the user staged is left alone. Commit messages are fixed strings per action, never a path or a name.
  • Sync is fetch, then the remote-commit rollback check (the last-seen remote commit must be an ancestor of the fetched head), then verification of the union through a read-only store over the fetched tree before anything is merged, then merge, then push. A refused verification leaves local state untouched.
  • A merge conflict on a vault path is corruption (exit 2); a conflict only on other paths aborts the merge and tells the user to merge their own files first (exit 4). No rebase, commit --amend, reset --hard of a published commit or push --force appears in the package, and a test scans its source for those argument strings.
  • A push rejected because the remote moved (non-fast-forward, "fetch first", cannot lock ref, failed to update ref) loops back to the fetch with jittered exponential backoff, at most five attempts (group 1 decision 3). Any other push failure keeps the local commits queued (offline-first).
  • An embedded vault shares a branch with code, so Sync refuses to push local commits that touch paths outside the vault unless --push-all is given. Files vaultfold itself owns at the repository root are exempt through SyncOptions.OwnedPaths, which the CLI fills with vault.toml, .dockerignore and .npmignore (group 1 decision 7, group 6 decision 7). This was ADR-pending in group 1 and is decided here: vaultfold-owned repository files are not "the user's unrelated work".
  • A brand-new remote with no branch yet skips the foreign-commit check and the push creates the branch (group 1 decision 1). Once a last-seen remote commit is on record, a remote whose branch has vanished is a rollback, not a fresh start (group 1 decision 2, ADR-pending in group 1 and decided here): anti-rollback outranks the empty-remote convenience.

Consequences

  • ADR 0041 amends the rule that hooks run as configured: vault-branch commits and pushes run with an empty hooks directory, so repository hooks never see them. Hooks still run for same-branch and standalone vaults.
  • vaultfold works with every remote, credential setup, proxy and signing policy that the user's git already works with, and a failure can be reproduced by running the same git command by hand.
  • git 2.30 or newer on PATH is a runtime dependency of git-backed vaults. A missing or old git is exit 4 with a message saying so.
  • gitstore imports os/exec, so it is not part of the gomobile surface of core/; a mobile client needs another way to reach a git-hosted vault, which is left to the mobile changes (see core/README.md).
  • Each operation costs process spawns. The read-only tree store keeps one long-lived git cat-file --batch to bound that for folds of a fetched tree.
  • Invariants hold against hostile user configuration only because of the pins above; a new git option that changes merge or push behavior would need a new pin. The source-scan test catches forbidden commands, not new configuration.
  • The vanished-branch rollback (group 1 decision 2) is implemented in checkRollback but still has no test named for it; the first change that touches sync should add one.

Alternatives considered

  • go-git, a pure-Go library. It would remove the runtime dependency and the process spawns, but supports only a subset of the configuration above (SSH agent and config details, credential helpers, includeIf, signing, hooks), and every gap becomes a "works with git, fails with vaultfold" support case. Anyone with a git-backed vault already has git installed.
  • libgit2 through cgo. Rejected with cgo itself: the project builds CGO-free for cross-compilation and later gomobile (ADR 0013), and libgit2 shares go-git's configuration gaps.
  • git pull or pull --rebase for sync. Rejected: the outcome would depend on pull.rebase and related user settings, and a rebase rewrites local commits, which the storage-backends spec forbids.