worktree

Documentation

Index

• func Add(repo, branch, baseDir, startPoint string) (string, error)
• func DirtyStatus(wtPath string) (string, error)
• func Remove(repo, wtPath string) error
• func RemoveAll(phases []Phase, baseDir string) error
• type BranchResolution
  • func ResolveBranchName(repo, base string) BranchResolution
• type Phase

Functions

func Add

func Add(repo, branch, baseDir, startPoint string) (string, error)

Add creates a git worktree for the given repo at the specified branch. The worktree is placed at baseDir/<repo-basename>/ . Returns the absolute path to the created worktree.

If the branch does not already exist in the repo, it is created from startPoint. Pass "" to let git default to HEAD (typical per-ticket workflow: user starts from main, spawns new branch off it). Callers handling a merged-base rename should pass an explicit remote ref like "origin/main" so the new branch doesn't inherit whatever HEAD happens to point at.

If the branch already exists, we attach the worktree to it and ignore startPoint.

func DirtyStatus

func DirtyStatus(wtPath string) (string, error)

DirtyStatus returns the output of `git status --porcelain` for the worktree. An empty string means clean (no staged, unstaged, or untracked changes). Non-empty means there's work that would be lost on a `git worktree remove --force`. If the worktree path doesn't exist or isn't a git working tree, returns "" and no error — nothing to preserve.

func Remove

func Remove(repo, wtPath string) error

Remove removes a git worktree that was previously added. It runs `git worktree remove` from the original repo.

func RemoveAll

func RemoveAll(phases []Phase, baseDir string) error

RemoveAll removes all worktrees for a sandbox by cleaning up the sandbox's worktree directory. It runs `git worktree remove` for each phase, then removes the directory. Accumulates errors from every phase so a single failure doesn't stop cleanup.

Types

type BranchResolution

type BranchResolution struct {
	Branch     string // name to use (may equal Base, or Base-N)
	Base       string // the name the caller started with
	StartPoint string // git rev to fork from; "" means HEAD (branch already exists)
	Reused     bool   // an existing branch was reused (no commit/history lost)
	WasMerged  bool   // an earlier name in the chain had a merged PR — we bumped past it
	MergedPR   int    // PR number of the most-recent merged ancestor (0 if unknown)
}

BranchResolution is the outcome of ResolveBranchName: the branch name to actually use plus any context about why it may differ from the base the user asked for.

func ResolveBranchName

func ResolveBranchName(repo, base string) BranchResolution

ResolveBranchName decides the branch name to use for new work on repo, given a desired base name. The walk:

1. Try `base`. If it doesn't exist: create it fresh.
2. If `base` exists AND its PR is merged: try `base-2`. Continue.
3. If any candidate exists and is NOT merged (open PR, no PR, closed-unmerged): reuse it. We don't want to spawn `-N+1` every `destroy`/`run` cycle when `-N` is still in-flight.
4. If a candidate doesn't exist yet but a previous one was merged: create that fresh from origin/<default>.

gh must be on PATH and authenticated for the merged-detection to fire; without it we treat every branch as "not merged" and reuse the base. Fails safe: a user without gh gets predictable reuse, not surprise suffixes.

type Phase

type Phase struct {
	Repo     string
	Branch   string
	Worktree string
	Order    int
}

Phase mirrors config.Phase to avoid circular imports.