worktrees

package
v0.23.0 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 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
	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"`
}

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

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"`
	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.

type ListOptions added in v0.18.0 

type ListOptions struct {
	ProjectsRoot string
	Task         string
	Base         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.

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.