Documentation
¶
Overview ¶
Package worktree manages ephemeral git worktrees used as isolated sandboxes: the agent works inside one, and changes are reviewed and merged or discarded on exit. It is a thin, stateless wrapper over `git worktree` — lifecycle and session wiring live in the caller (bootstrap.Runtime).
Index ¶
- Variables
- func Branch(slug string) string
- func CopyIncludes(repoRoot, dir string, patterns []string) (failed []string, err error)
- func Create(repoRoot, slug string) (dir, branch string, err error)
- func CreateOrReuse(repoRoot, slug string) (dir, branch string, err error)
- func Diff(dir string) (string, error)
- func Dir(repoRoot, slug string) string
- func HasChanges(dir string) (bool, error)
- func Remove(repoRoot, dir, branch string, force bool) (branchKept bool, err error)
- func Slug(name string) string
- type Info
Constants ¶
This section is empty.
Variables ¶
var DefaultIncludes = []string{".env", ".env.local"}
DefaultIncludes are the gitignored files copied into a fresh worktree so it can actually run: a clean checkout omits everything git ignores, and a missing .env is the most common reason a sandboxed build/test fails. Shared by the leader-side /worktree command and teammate isolation.
Functions ¶
func CopyIncludes ¶
CopyIncludes copies gitignored files matching patterns from repoRoot into the fresh worktree, so it has the local files (.env, etc.) it needs to actually run — a clean checkout omits everything git ignores. It returns the relative paths it found but could NOT copy (e.g. a permission error), so the caller can warn rather than leave the sandbox silently missing config; err is reserved for the lookup itself failing. A file absent from the source is simply not listed, never a failure.
func Create ¶
Create adds a worktree at Dir(repoRoot, slug) on a new branch codebot/<slug>, based on the repo's current HEAD. It fails if the slug is already in use so the caller can ask for a different name.
func CreateOrReuse ¶
CreateOrReuse returns the worktree for slug, creating it when absent and reusing the existing checkout when a previous run left one behind — e.g. a teammate that kept uncommitted changes on exit and is later woken to reclaim its sandbox. Unlike Create it does not fail on an existing directory, but it reuses one ONLY after confirming it is the registered worktree for branch: a leftover plain directory (from a half-failed create) is not a sandbox, and pointing tools at it would let `git` walk up to the parent repo and corrupt cleanup decisions. A mismatch is an error, not a silent reuse.
func Diff ¶
Diff returns the worktree's changes for review. It diffs against HEAD so both staged and unstaged edits show (a plain `git diff` would miss staged work and diverge from HasChanges, which also counts staged + untracked), then appends untracked filenames so a clean-tree-with-new-files sandbox doesn't render as an empty diff.
func Dir ¶
Dir returns the worktree's working directory: <repoRoot>/.codebot/worktrees/<slug>. It lives under .codebot/ (already gitignored), so the checkout never pollutes the user's status.
func HasChanges ¶
HasChanges reports whether the worktree has any uncommitted changes (tracked or untracked).
func Remove ¶
Remove deletes the worktree and its branch. With force it discards everything (worktree --force + branch -D) — the caller asked to throw the work away. Without force it is data-safe by construction: `git worktree remove` refuses a dirty checkout (uncommitted or untracked files), and `git branch -d` refuses a branch with commits not reachable from any other ref. So a sandbox the agent committed into keeps its branch even when the working tree is clean. The returned branchKept reports exactly that case (worktree gone, branch retained because it held unmerged commits) so the caller can tell the user where the work survived.
Source Files