Documentation
¶
Overview ¶
Package worktree — opt-in git-worktree isolation per dispatch (ADR-014 T5, design from the 2026-04-26 multi-CLI fan-out).
Lifecycle:
- `clawtool send --isolated` resolves the operator's repo root.
- Worktree.Manager.Create reserves `~/.cache/clawtool/worktrees/{taskID}` under an advisory file lock and shells out to `git worktree add --detach`.
- Transport.Send dispatches the upstream agent with the worktree as cwd; the agent can stage/commit freely without touching the operator's working tree.
- On success the cleanup func removes the worktree and prunes git's bookkeeping. On failure with `--keep-on-error` the worktree is left in place and `clawtool worktree show <taskID>` points the operator at it.
Per ADR-007 we wrap `git worktree add/remove/prune` shell-outs; we never reimplement git. The worktree dir gets a marker JSON so `clawtool worktree gc` can reap orphans whose owning process died.
Index ¶
Constants ¶
const MarkerFilename = ".clawtool-worktree.json"
MarkerFilename is the JSON marker every worktree carries. GC inspects it to decide reapability.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GCManager ¶
GCManager exposes GC on the *manager type for the CLI subcommand. We don't add it to the Manager interface to keep the dispatch path minimal; gc is a maintenance command.
func AsGCManager ¶
AsGCManager surfaces the GC method on a Manager built by New(). Returns nil for non-default Managers.
type Manager ¶
type Manager interface {
// Create reserves a worktree at ~/.cache/clawtool/worktrees/{taskID},
// shells out to git worktree add, stamps a marker, and returns the
// workdir path plus a cleanup func. The cleanup is idempotent and
// safe to call from multiple goroutines.
//
// Concurrency: holds a per-repo advisory file lock around the
// add/remove/prune operations. Two parallel Create calls against
// the same repo serialise creation but the workdirs (and dispatch
// runs) execute in parallel.
Create(ctx context.Context, repoPath, taskID, agent string) (workdir string, cleanup func(), err error)
}
Manager creates and disposes ephemeral git worktrees.
type Marker ¶
type Marker struct {
TaskID string `json:"task_id"`
RepoRoot string `json:"repo_root"`
BaseRef string `json:"base_ref"`
Agent string `json:"agent"`
PID int `json:"pid"`
CreatedAt time.Time `json:"created_at"`
}
Marker is the on-disk state we stamp into each worktree. PID and CreatedAt let GC distinguish live work from orphans.
func ReadMarker ¶
ReadMarker decodes the marker JSON at workdir. Used by GC.
Source Files