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.CommandContextwith 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=0when there is no terminal (CI fails fast rather than hanging on a credential prompt),GIT_OPTIONAL_LOCKS=0for read-only commands. Porcelain and-zoutput formats only. - Configuration that would break the invariants is pinned per call with
-c:merge --no-edit --ffwithmerge.renames=false,merge.autoStash=falseandrerere.enabled=false(group 1 decision 4).pullis never used, sopull.rebasenever applies. - The binary is resolved with
exec.LookPathwhen 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.nameanduser.emailare 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
Commitstaged (group 1 decision 6).
Adds-only merges:
Commitstages only the named vault paths and runsgit commit --only, so anything else the user staged is left alone. Commit messages are fixed strings per action, never a path or a name.Syncis 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 --hardof a published commit orpush --forceappears 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
Syncrefuses to push local commits that touch paths outside the vault unless--push-allis given. Files vaultfold itself owns at the repository root are exempt throughSyncOptions.OwnedPaths, which the CLI fills withvault.toml,.dockerignoreand.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.
git2.30 or newer onPATHis a runtime dependency of git-backed vaults. A missing or old git is exit 4 with a message saying so.gitstoreimportsos/exec, so it is not part of the gomobile surface ofcore/; a mobile client needs another way to reach a git-hosted vault, which is left to the mobile changes (seecore/README.md).- Each operation costs process spawns. The read-only tree store keeps
one long-lived
git cat-file --batchto 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
checkRollbackbut 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 pullorpull --rebasefor sync. Rejected: the outcome would depend onpull.rebaseand related user settings, and a rebase rewrites local commits, which the storage-backends spec forbids.