worktree

Documentation

Overview

Package worktree provides actions for managing stackit-managed worktrees.

Index

• Constants
• func DetachAction(ctx *app.Context, opts DetachOptions) error
• func OpenAction(ctx *app.Context, opts OpenOptions) (string, error)
• func RemoveAction(ctx *app.Context, opts RemoveOptions) error
• func ResolveApprovedHooks(ctx *app.Context) ([]string, error)
• func RunPostCreateHooks(ctx *app.Context, worktreePath string) error
• func RunResolvedHooks(hooks []string, worktreePath string, out output.Output)
• type AttachOptions
• type AttachResult
  • func AttachAction(ctx *app.Context, opts AttachOptions) (*AttachResult, error)
• type CreateOptions
• type CreateResult
  • func CreateAction(ctx *app.Context, opts CreateOptions) (*CreateResult, error)
  • func CreateAnchoredWorktreeForBranch(ctx *app.Context, branchName string, name string, scope string) (*CreateResult, error)
• type DetachOptions
• type Entry
• type ListOptions
• type ListResult
  • func ListAction(ctx *app.Context, _ ListOptions) (*ListResult, error)
• type OpenOptions
• type PruneOptions
• type PruneResult
  • func PruneAction(ctx *app.Context, opts PruneOptions) (*PruneResult, error)
• type RegistrationState
• type RemoveOptions
• type RepairEntry
• type RepairOptions
• type RepairResult
  • func RepairAction(ctx *app.Context, opts RepairOptions) (*RepairResult, error)
• type SkippedEntry

Constants

const HookTimeout = 60 * time.Second

HookTimeout is the maximum duration a hook can run before being killed

Functions

func DetachAction

func DetachAction(ctx *app.Context, opts DetachOptions) error

DetachAction removes a worktree while preserving all branches

func OpenAction

func OpenAction(ctx *app.Context, opts OpenOptions) (string, error)

OpenAction returns the path to a worktree for a stack

func RemoveAction

func RemoveAction(ctx *app.Context, opts RemoveOptions) error

RemoveAction removes a worktree for a stack

func ResolveApprovedHooks

func ResolveApprovedHooks(ctx *app.Context) ([]string, error)

ResolveApprovedHooks loads the project config, checks for approvals, and prompts the user for any unapproved hooks. Returns the list of approved hook commands. This must be called from the main thread (it may prompt interactively).

func RunPostCreateHooks

func RunPostCreateHooks(ctx *app.Context, worktreePath string) error

RunPostCreateHooks runs any configured post-worktree-create hooks. It loads the project config, checks for approvals, prompts for unapproved hooks, and executes approved hooks in the worktree directory.

func RunResolvedHooks

func RunResolvedHooks(hooks []string, worktreePath string, out output.Output)

RunResolvedHooks executes a pre-resolved list of hooks in the given directory. No prompting is performed — safe for parallel use.

Types

type AttachOptions

type AttachOptions struct {
	Branch string // Any branch in the stack (we find the stack root)
	Name   string // Optional worktree name (defaults to stack root name)
}

AttachOptions contains options for the attach action

type AttachResult

type AttachResult struct {
	Name         string // The name of the worktree
	AnchorBranch string // Hidden worktree anchor branch
	Path         string // The path to the worktree
}

AttachResult contains the results of attaching a worktree

func AttachAction

func AttachAction(ctx *app.Context, opts AttachOptions) (*AttachResult, error)

AttachAction creates a worktree for an existing stack

type CreateOptions

type CreateOptions struct {
	Name  string // User-provided name for the worktree
	Scope string // Optional scope to set on the anchor branch
}

CreateOptions contains options for the create action

type CreateResult

type CreateResult struct {
	Name         string // The name of the worktree
	AnchorBranch string // The name of the anchor branch
	Path         string // The path to the worktree
}

CreateResult contains the results of creating a worktree

func CreateAction

func CreateAction(ctx *app.Context, opts CreateOptions) (*CreateResult, error)

CreateAction creates a new worktree with an anchor branch

func CreateAnchoredWorktreeForBranch

func CreateAnchoredWorktreeForBranch(ctx *app.Context, branchName string, name string, scope string) (*CreateResult, error)

CreateAnchoredWorktreeForBranch creates a hidden anchor for branchName, moves branchName under it without rebasing, and opens a worktree checked out on branchName.

type DetachOptions

type DetachOptions struct {
	NameOrBranch string // Worktree name or anchor branch
	Force        bool   // Allow detach even with uncommitted changes
}

DetachOptions contains options for the detach action

type Entry

type Entry struct {
	Name              string            `json:"name"`          // User-provided name
	AnchorBranch      string            `json:"anchor_branch"` // Registered anchor branch name
	Path              string            `json:"path"`
	Exists            bool              `json:"exists"`                   // Whether the path still exists on disk
	StackSize         int               `json:"stack_size"`               // Number of real branches in the stack
	CurrentBranch     string            `json:"current_branch,omitempty"` // Branch currently checked out in this worktree
	IsDirty           bool              `json:"is_dirty"`
	RootBranches      []string          `json:"root_branches,omitempty"`  // Real stack roots visible to the user
	RegistrationState RegistrationState `json:"registration_state"`       // Whether the registration is anchored, legacy, or invalid
	StatusMessage     string            `json:"status_message,omitempty"` // Human-readable summary of current state
	CanRemove         bool              `json:"can_remove"`               // Empty anchored worktree can be removed
	CanDetach         bool              `json:"can_detach"`               // Anchored worktree can be detached
	NeedsRepair       bool              `json:"needs_repair"`             // Registration requires repair before lifecycle actions
	IsCurrent         bool              `json:"is_current,omitempty"`     // Whether this is the current managed worktree
}

Entry represents a single managed worktree

type ListOptions

type ListOptions struct {
	NameOrBranch string
}

ListOptions contains options for the list action

type ListResult

type ListResult struct {
	Worktrees     []Entry
	CurrentAnchor string // Anchor branch of the worktree we're currently in (if any)
}

ListResult contains the results of listing worktrees

func ListAction

func ListAction(ctx *app.Context, _ ListOptions) (*ListResult, error)

ListAction lists all managed worktrees

type OpenOptions

type OpenOptions struct {
	AnchorBranch string // Anchor branch name to get path for
}

OpenOptions contains options for the open action

type PruneOptions

type PruneOptions struct {
	DryRun bool // If true, only show what would be pruned
}

PruneOptions contains options for the prune action

type PruneResult

type PruneResult struct {
	Pruned  []string       // Names of pruned worktrees
	Skipped []SkippedEntry // Worktrees that were skipped and why
}

PruneResult contains the results of pruning worktrees

func PruneAction

func PruneAction(ctx *app.Context, opts PruneOptions) (*PruneResult, error)

PruneAction removes all empty worktrees

type RegistrationState

type RegistrationState string

const (
	RegistrationStateOK      RegistrationState = "ok"
	RegistrationStateLegacy  RegistrationState = "legacy"
	RegistrationStateInvalid RegistrationState = "invalid"
)

type RemoveOptions

type RemoveOptions struct {
	AnchorBranch string // Anchor branch name to remove worktree for
	Force        bool   // Force removal even if worktree has uncommitted changes
}

RemoveOptions contains options for the remove action

type RepairEntry

type RepairEntry struct {
	Name         string `json:"name"`
	Action       string `json:"action"`
	AnchorBranch string `json:"anchor_branch,omitempty"`
}

type RepairOptions

type RepairOptions struct {
	NameOrBranch string
}

type RepairResult

type RepairResult struct {
	Repaired []RepairEntry  `json:"repaired"`
	Skipped  []SkippedEntry `json:"skipped,omitempty"`
}

func RepairAction

func RepairAction(ctx *app.Context, opts RepairOptions) (*RepairResult, error)

type SkippedEntry

type SkippedEntry struct {
	Name   string
	Reason string
}

SkippedEntry represents a worktree that was skipped during pruning