worktrees

package
v0.25.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 9, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package worktrees creates and validates the isolated Git worktrees used for human and agent development. Canonical clones remain clean, current mirrors of their base branches; all feature work lives below .wb/worktrees.

Index

Constants

View Source 
const SecureCanonicalGitHelperArgument = "--wb-internal-canonical-git"

SecureCanonicalGitHelperArgument selects the private WB child-process path that validates retained canonical root and Git-directory descriptors before executing a canonical-clone Git operation.

View Source 
const SecureCleanupGitHelperArgument = "--wb-internal-cleanup-git"

SecureCleanupGitHelperArgument selects the private WB child process that runs cleanup Git commands from retained canonical and worktree descriptors.

View Source 
const SecureStageCanonicalGitHelperArgument = "--wb-internal-stage-canonical-git"

SecureStageCanonicalGitHelperArgument selects the private WB child-process path that combines an inherited private stage with an inherited canonical Git capability. It is deliberately separate from SecureStageGitHelper so the small stage inspection helper never needs a Git capability.

View Source 
const SecureStageGitHelperArgument = "--wb-internal-stage-git"

SecureStageGitHelperArgument selects the private WB child-process path that enters the stage directory from inherited file descriptor 3 before running Git. It is handled before normal CLI parsing and is not a user command.

Variables

This section is empty.

Functions

func CanonicalRepositoryPath added in v0.22.2 

func CanonicalRepositoryPath(projectsRoot, repository string) (string, error)

CanonicalRepositoryPath validates one owner/repository slug with the same strict parser used by Create, then returns its canonical-clone path below projectsRoot. Callers that perform work before Create (for example managed hook refresh) must use this resolver rather than constructing a path from user-supplied segments themselves.

func DefaultCleanupReportDir added in v0.18.0 

func DefaultCleanupReportDir(home string, now time.Time) string

DefaultCleanupReportDir returns the durable audit directory for one apply, below the already-resolved WB home directory (see wbhome.Root).

func OriginSlug 

func OriginSlug(ctx context.Context, path string) (string, error)

OriginSlug returns the owner/repository identity of path's origin remote.

func RunSecureCanonicalGitHelper added in v0.22.2 

func RunSecureCanonicalGitHelper(args []string) int

RunSecureCanonicalGitHelper runs Git from the inherited canonical root only after opening and comparing its `.git` entry with the inherited Git directory descriptor. This prevents Git's own discovery from treating a substituted `.git` pathname as authority.

func RunSecureCleanupGitHelper added in v0.22.2 

func RunSecureCleanupGitHelper(args []string) int

RunSecureCleanupGitHelper is the child half of descriptor-anchored cleanup Git operations. FD 3 is the canonical repository, FD 4 is its held `.git` directory, FD 5 is the held worktree parent, and FD 6 is the target worktree. Both canonical descriptors and the optional parent/worktree pair are reauthorized immediately before Git executes.

func RunSecureStageCanonicalGitHelper added in v0.22.2 

func RunSecureStageCanonicalGitHelper(args []string) int

RunSecureStageCanonicalGitHelper is the last authority before Git creates a staged checkout. FD 3 is the private stage, FD 4 is the canonical root, and FD 5 is its `.git` directory. The stage target is derived only after the inherited stage passes containment; Git itself receives the inherited `.git` directory through GIT_DIR instead of resolving a lexical canonical path.

func RunSecureStageGitHelper added in v0.22.2 

func RunSecureStageGitHelper(args []string) int

RunSecureStageGitHelper is the child-side half of a secure worktree add. The caller passes the stage directory in fd 3 via exec.Cmd.ExtraFiles. This child alone changes its current directory from that immutable descriptor, then runs Git with only the already-constructed arguments supplied by its parent. It returns an ordinary process exit code for cmd/wb's early main dispatch and for the worktrees package's test helper.

func ValidateRepositories added in v0.22.2 

func ValidateRepositories(repositories []string) ([]string, error)

ValidateRepositories rejects unsafe and duplicate repository coordinates before callers mutate canonical clones, hooks, or WB home. It also returns a sorted copy so every later phase has deterministic order.

Types

type CleanupOptions added in v0.18.0 

type CleanupOptions struct {
	ProjectsRoot string
	Task         string
	Base         string
	// Filter narrows both which candidates are validated and which are acted
	// on to those whose owner/repository slug contains this substring — see
	// ListOptions.Filter. An empty Filter matches everything, preserving
	// today's behavior exactly.
	Filter       string
	AllMerged    bool
	Apply        bool
	DeleteRemote bool
	OlderThan    time.Duration
	ReportDir    string
	Now          func() time.Time
	// contains filtered or unexported fields
}

CleanupOptions controls planning and removal of merged WB tasks.

type CleanupOutcome added in v0.18.0 

type CleanupOutcome struct {
	Results     []CleanupResult  `json:"results"`
	ReportPath  string           `json:"report_path,omitempty"`
	Diagnostics []ListDiagnostic `json:"diagnostics,omitempty"`
}

CleanupOutcome contains the decisions plus the durable audit report written before any destructive apply.

Diagnostics never abort a run. A malformed candidate inside the selection (see CleanupOptions.Filter) is skipped and reported here as a warning, and blocks eligibility only for its own coordinated task — the same all-or-nothing unit blockUnsafeTasks already applies to an unclean, locked, or unmerged sibling. Every other task in the run proceeds normally.

func Cleanup added in v0.18.0 

func Cleanup(ctx context.Context, options CleanupOptions) (CleanupOutcome, error)

Cleanup plans or applies cleanup for one task or every safely merged task. A coordinated task is all-or-nothing: one unsafe repository blocks all of its worktrees.

type CleanupResult added in v0.18.0 

type CleanupResult struct {
	ListResult
	Eligible      bool   `json:"eligible"`
	Applied       bool   `json:"applied"`
	RemoteDeleted bool   `json:"remote_deleted"`
	Reason        string `json:"reason,omitempty"`
}

CleanupResult records one repository's cleanup decision and outcome.

type CreateOptions 

type CreateOptions struct {
	ProjectsRoot string
	Operation    string
	Branch       string
	Base         string
	Resume       bool
	// contains filtered or unexported fields
}

CreateOptions controls one coordinated worktree creation operation.

type CreateResult 

type CreateResult struct {
	Repository   string `json:"repository"`
	CanonicalDir string `json:"canonical_dir"`
	WorktreeDir  string `json:"worktree_dir"`
	Branch       string `json:"branch"`
	Base         string `json:"base"`
	Action       string `json:"action"`
}

CreateResult identifies the isolated checkout prepared for one repository.

func Create 

func Create(ctx context.Context, repositories []string, options CreateOptions) ([]CreateResult, error)

Create synchronizes each clean canonical base branch with origin, then creates (or explicitly resumes) the corresponding isolated worktree.

Synchronization happens before any branch is created. This is deliberate: every new feature branch must be based on the latest remote base, while an unsafe canonical clone causes the whole request to fail before feature work starts.

type GuardOptions 

type GuardOptions struct {
	ProjectsRoot string
	Base         string
}

GuardOptions defines the local checkout policy checked by hooks and agents.

type GuardResult 

type GuardResult struct {
	Path          string `json:"path"`
	CanonicalDir  string `json:"canonical_dir"`
	WorktreesRoot string `json:"worktrees_root"`
	Branch        string `json:"branch"`
	Kind          string `json:"kind"`
	Transient     bool   `json:"transient,omitempty"`
}

GuardResult describes a checkout that satisfies the worktree policy.

func Guard 

func Guard(ctx context.Context, path string, options GuardOptions) (GuardResult, error)

Guard verifies that path is either a clean canonical checkout of the base branch or a non-base linked worktree in WB's central worktree hierarchy.

type ListDiagnostic added in v0.22.2 

type ListDiagnostic struct {
	Task          string `json:"task,omitempty"`
	WorktreesRoot string `json:"worktrees_root,omitempty"`
	Path          string `json:"path"`
	Message       string `json:"message"`
}

ListDiagnostic describes a malformed task-layout candidate that was skipped without hiding valid sibling worktrees. It is intentionally separate from ListResult so cleanup can never mistake an unvalidated path for a safe linked checkout. WorktreesRoot is carried alongside Task so a diagnostic can be matched back to the exact coordinated task it belongs to even when more than one resolver-recognized layout is being read at once (see wbhome.Resolve) — Task name alone is not always unique across layouts.

type ListOptions added in v0.18.0 

type ListOptions struct {
	ProjectsRoot string
	Task         string
	Base         string
	// Filter narrows the inventory to candidates whose owner/repository slug
	// (or, for a candidate that cannot be identified that cleanly, whatever
	// raw path-derived identity is available) contains this substring — the
	// same "only repos whose org/name contains this substring" semantics as
	// the root --filter flag elsewhere in WB. An empty Filter matches
	// everything, exactly like today. Filtering happens before a candidate's
	// diagnostic or result is retained, so a candidate outside the selection
	// can neither appear in the report nor influence it.
	Filter string
	GitHub bool
}

ListOptions selects WB-managed task worktrees and optional GitHub PR state.

type ListOutcome added in v0.22.2 

type ListOutcome struct {
	Results     []ListResult     `json:"results"`
	Diagnostics []ListDiagnostic `json:"diagnostics,omitempty"`
}

ListOutcome preserves the valid local inventory while exposing every deterministic malformed-candidate diagnostic encountered during scanning.

func ListWithDiagnostics added in v0.22.2 

func ListWithDiagnostics(ctx context.Context, options ListOptions) (ListOutcome, error)

ListWithDiagnostics inventories every resolver-recognized layout. It never descends below a Git root, which prevents ordinary repository directories such as .claude, .github, source, and generated trees from being re-read as task-level repositories.

type ListResult added in v0.18.0 

type ListResult struct {
	Task              string       `json:"task"`
	Repository        string       `json:"repository"`
	CanonicalDir      string       `json:"canonical_dir"`
	WorktreeDir       string       `json:"worktree_dir"`
	WorktreesRoot     string       `json:"worktrees_root"`
	Branch            string       `json:"branch"`
	Base              string       `json:"base"`
	HeadSHA           string       `json:"head_sha"`
	RemoteHeadSHA     string       `json:"remote_head_sha,omitempty"`
	Clean             bool         `json:"clean"`
	LocallyMerged     bool         `json:"locally_merged"`
	Locked            bool         `json:"locked"`
	LastCommit        time.Time    `json:"last_commit"`
	OpenPullRequest   *PullRequest `json:"open_pull_request,omitempty"`
	MergedPullRequest *PullRequest `json:"merged_pull_request,omitempty"`
}

ListResult describes one linked checkout below the WB task hierarchy.

func List added in v0.18.0 

func List(ctx context.Context, options ListOptions) ([]ListResult, error)

List inspects real Git worktrees. It stays local unless GitHub is requested. Callers that present diagnostics should use ListWithDiagnostics.

type PullRequest added in v0.18.0 

type PullRequest struct {
	Number  int        `json:"number"`
	URL     string     `json:"url"`
	State   string     `json:"state"`
	Base    string     `json:"base"`
	HeadSHA string     `json:"head_sha"`
	Merged  *time.Time `json:"merged_at,omitempty"`
}

PullRequest is the GitHub evidence used to decide whether a branch is safe to clean up. HeadSHA must match the current branch tip.

type RepositoryRenameMismatchError added in v0.25.3 

type RepositoryRenameMismatchError struct {
	Worktree            string
	Owner               string
	PathRepository      string
	CanonicalRepository string
}

RepositoryRenameMismatchError reports a managed worktree whose on-disk <task>/<owner>/<repository> path segment no longer names its canonical clone's current repository — exactly the signature a GitHub repository rename leaves behind on every worktree that predates it. Its Error text is unchanged from the plain fmt.Errorf this replaced, so `wb worktree guard` (which still treats this as a hard, single-checkout rejection) reports the same message as before. List and Cleanup recognize it structurally via errors.As to survive it: this is ordinary history, not corruption, and a stale path segment alone is not evidence that anyone's work is at risk.

func (*RepositoryRenameMismatchError) Error added in v0.25.3 

func (mismatch *RepositoryRenameMismatchError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.