Documentation
¶
Overview ¶
Package vcs is the git surface for the agent's diff-review flow: the host-side helpers that let a human SEE what the agent changed and decide whether to keep it, before anything is committed. It is the other half of the trust layer (sandbox/gated gates what the agent RUNS; this reviews what it WROTE).
It shells out to the `git` binary rather than linking a git library on purpose: these run on the host against the user's real repo (not inside the sandbox), the operations are a handful of porcelain commands, and matching the user's own git exactly (config, hooks, version) is a feature, not a thing to reimplement. Every call is `git -C <dir> …` so the working directory is explicit and nothing depends on the process's cwd.
Index ¶
- func Apply(ctx context.Context, dir, patchPath string) error
- func Commit(ctx context.Context, dir, msg string) error
- func Diff(ctx context.Context, dir string) (string, error)
- func DiffTreeNames(ctx context.Context, dir, a, b string) ([]string, error)
- func DiffTrees(ctx context.Context, dir, a, b string) (string, error)
- func DiffTreesStat(ctx context.Context, dir, a, b string) (string, error)
- func Discard(ctx context.Context, dir string) error
- func IsClean(ctx context.Context, dir string) (bool, error)
- func IsRepo(ctx context.Context, dir string) bool
- func RestoreTree(ctx context.Context, dir, tree string) error
- func StageAll(ctx context.Context, dir string) error
- func Unstage(ctx context.Context, dir string) error
- func WorktreeCollect(ctx context.Context, dir, patchPath string) (bool, error)
- func WorktreeRemove(ctx context.Context, dir string) error
- func WriteTree(ctx context.Context, dir string) (string, error)
- func WriteTreeCached(ctx context.Context, dir, indexPath string) (string, error)
- type WorktreeInfo
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Apply ¶
Apply applies a patch file to the working tree (`git apply`). Used by the gate-only evaluation harness to install a banked candidate diff.
func Commit ¶
Commit records the staged changes with msg. It assumes StageAll already ran (the -review flow stages, shows the diff, then commits on approval).
func Diff ¶
Diff returns the staged diff (`git diff --cached`) — the full, reviewable set of the agent's changes after StageAll, including new files. Empty output means the agent changed nothing.
func DiffTreeNames ¶
DiffTreeNames returns the paths whose content differs between two tree objects.
func DiffTrees ¶
DiffTrees returns the unified diff between two tree objects (as produced by WriteTree). Empty output means the trees are identical.
func DiffTreesStat ¶
DiffTreesStat returns git's stat summary between two tree objects. --stat alone: combining it with --shortstat printed the "N files changed" summary line twice (caught by the standing-block exact golden, 2026-07-09).
func Discard ¶
Discard throws the agent's work away and returns the tree to HEAD: it unstages + reverts tracked changes (reset --hard) and removes new untracked files (clean -fd). Safe precisely because IsClean was required first — there is no pre-existing uncommitted work of the user's to lose.
func IsClean ¶
IsClean reports whether dir is a git work tree with NO uncommitted changes (tracked or untracked). The -review flow requires this up front: a clean tree means the post-run diff is unambiguously the agent's work, and discarding is safe because nothing of the user's is mixed in. A dir that isn't a git repo returns an error, not false — "not a repo" and "dirty repo" need different messages to the user.
func IsRepo ¶
IsRepo reports whether dir is inside a git work tree. Unlike IsClean it does not care about dirtiness — the review gate diffs against a recorded start state, so a dirty tree is fine; only "no repo at all" disables it.
func RestoreTree ¶
RestoreTree restores the working tree to the exact content captured in tree, where tree is a hash returned by WriteTree. It uses a temporary index for all git plumbing, so the user's real index is not read or modified. Files present in the current working tree but absent from tree are removed; modified and deleted files are restored from tree.
func StageAll ¶
StageAll stages every change — modified, deleted, and NEW files — so the review diff and a subsequent commit include the agent's brand-new files (a plain `git diff` would miss them). It is the setup step for Diff/Commit.
func Unstage ¶
Unstage moves the staged changes back to the working tree (`git reset`), leaving the files on disk for the human to inspect or edit by hand. It is the "keep, but don't commit" outcome of the review.
func WorktreeCollect ¶
WorktreeCollect stages untracked paths as intent-to-add, then writes a binary patch for all changes relative to HEAD. It returns changed=false when the worktree is clean and no patch was written. When patchPath is empty it only reports whether changes exist.
func WorktreeRemove ¶
WorktreeRemove removes a throwaway worktree and prunes stale worktree metadata.
func WriteTree ¶
WriteTree snapshots the ENTIRE working tree — tracked and untracked files, gitignore respected — as a git tree object and returns its hash. It stages into a TEMPORARY index (GIT_INDEX_FILE), so the repository's real index, HEAD, and the user's staged state are untouched; the only side effect is loose blobs in the object store, which gc reclaims. This is the review gate's diff baseline: two WriteTree calls bracket the agent's work and DiffTrees renders exactly what changed between them, new files included.
func WriteTreeCached ¶
WriteTreeCached is WriteTree's warm-index variant. It stages into the caller's persistent indexPath (never the repository index), so repeated calls can reuse git's stat cache while preserving WriteTree's tracked+untracked, gitignore-aware semantics. The index path's parent is created if needed.
Types ¶
type WorktreeInfo ¶
WorktreeInfo is the provenance record for a throwaway worktree created by WorktreeAdd. Dir is the detached worktree path. BaseCommit is the full SHA the worktree is based on: HEAD when the main checkout was clean, the dirty-tree snapshot commit when it was dirty. DirtyFiles names the paths that differ between HEAD and the snapshot (sorted), nil when clean.
func WorktreeAdd ¶
func WorktreeAdd(ctx context.Context, origCwd string) (WorktreeInfo, error)
WorktreeAdd creates a throwaway detached worktree. Clean checkouts are based exactly on HEAD. Dirty checkouts are first snapshotted into a commit pinned under refs/driver-agent/baselines/<name> that includes tracked modifications and untracked, non-ignored files, so delegated work sees the orchestrator's current tree while patches still diff cleanly against the worktree's own HEAD.
Source Files