worktree

Documentation

Overview

Package worktree manages git worktree creation and teardown for Smith workers.

Each Smith operates in an isolated git worktree under .workers/<bead-id>/ in the anvil's repository directory. The worktree is branched from origin/main with a forge-prefixed branch name.

Index

• func BranchName(beadID string) string
• func CurrentBranch(ctx context.Context, repoPath string) (string, error)
• func LinkNodeModules(anvilPath, worktreePath string) error
• func ProbeNodeModules(label, anvilPath string)
• func RemoveWithRetry(ctx context.Context, path string) error
• func UnlinkReparsePoints(path string)
• func ValidateWorktreeDir(worktreePath string) error
• func VerifyAndRecoverMain(ctx context.Context, repoPath string) (recovered bool, originalBranch string, err error)
• type CreateOptions
• type Manager
  • func NewManager() *Manager
  • func (m *Manager) Create(ctx context.Context, anvilPath, beadID string, branch ...string) (*Worktree, error)
  • func (m *Manager) CreateEpicBranch(ctx context.Context, anvilPath, branchName string) error
  • func (m *Manager) CreateWithOptions(ctx context.Context, anvilPath, beadID string, opts CreateOptions) (*Worktree, error)
  • func (m *Manager) FetchBranch(ctx context.Context, anvilPath, branchName string) error
  • func (m *Manager) List(anvilPath string) ([]string, error)
  • func (m *Manager) Remove(ctx context.Context, anvilPath string, wt *Worktree) error
• type Worktree

Functions

func BranchName

func BranchName(beadID string) string

BranchName returns the canonical forge branch name for a bead ID. This matches the branch created by CreateWithOptions when no Branch override is provided. Callers outside this package use this to predict the branch name without creating a worktree (e.g. checking for un-PR'd remote work).

func CurrentBranch

func CurrentBranch(ctx context.Context, repoPath string) (string, error)

CurrentBranch returns the currently checked-out branch name for the repository at repoPath. Returns "HEAD" for detached HEAD state. Returns an error if git cannot determine the branch.

func LinkNodeModules

func LinkNodeModules(anvilPath, worktreePath string) error

LinkNodeModules is the exported form of linkNodeModules for use by packages that need to re-establish node_modules links after git operations.

func ProbeNodeModules

func ProbeNodeModules(label, anvilPath string)

ProbeNodeModules logs the mtime and entry count of each known node_modules location inside the given anvil directory. Checks the root and each subdirectory in nodeModulesDirs (matches linkNodeModules targets) so we see activity for client/frontend/etc. setups, not only repo-root node_modules. Purely diagnostic; never fails.

func RemoveWithRetry

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

RemoveWithRetry is the exported form of removeWithRetry for use by daemon-level stale directory cleanup.

func UnlinkReparsePoints

func UnlinkReparsePoints(path string)

UnlinkReparsePoints is the exported form of unlinkReparsePoints for use by other packages that need to safely remove worktree directories.

func ValidateWorktreeDir

func ValidateWorktreeDir(worktreePath string) error

ValidateWorktreeDir checks that the given directory is safe to run Smith in. If the directory is not inside any git repository (e.g. an os.MkdirTemp dir used by schematic or wicket), the check passes — there is no parent checkout to accidentally inherit. If the directory is inside a git repo, it must have a valid worktree .git file pointer to ensure isolation from the main checkout.

func VerifyAndRecoverMain

func VerifyAndRecoverMain(ctx context.Context, repoPath string) (recovered bool, originalBranch string, err error)

VerifyAndRecoverMain checks that the repository at repoPath is checked out to main, master, or a detached HEAD. If it is on a different branch, it attempts to recover by checking out main or master. It returns a boolean indicating whether recovery was attempted, the name of the original branch, and any error that occurred. If the current branch cannot be determined, it returns false, "", and the error.

Types

type CreateOptions

type CreateOptions struct {
	// Branch overrides the target branch name. Default: forge/<beadID>.
	Branch string
	// BaseBranch overrides the base ref to branch from. Default: origin/main
	// or origin/master (auto-detected). When set, the worktree branches from
	// origin/<BaseBranch> instead.
	BaseBranch string
	// ResetBranch, when true, resets an existing worktree branch back to the
	// base ref (origin/main or origin/<BaseBranch>) instead of reusing the
	// branch as-is. This discards all previous commits on the branch,
	// preventing cascading junk from failed pipeline runs.
	ResetBranch bool
	// Quiet suppresses git command stdout/stderr output (redirects to
	// io.Discard). Use this when creating worktrees from a TUI to avoid
	// corrupting the terminal's alt-screen with git progress output.
	Quiet bool
	// LocalHead, when true, skips the assertOnMainBranch safety check and
	// git fetch, and bases the worktree from the current local HEAD rather
	// than origin/main. Use for read-only scan worktrees where "scan the
	// working tree as-is" semantics are required and remote state should not
	// be fetched.
	LocalHead bool
	// SkipNodeModulesJunction, when true, skips linking node_modules from
	// the main checkout. Used for dependency-update beads where npm install
	// must write to a local node_modules to avoid corrupting the main
	// checkout's dependencies.
	SkipNodeModulesJunction bool
}

CreateOptions controls worktree creation behaviour.

type Manager

type Manager struct {
	// WorkersDir is the directory name under each anvil for worktrees.
	// Default: ".workers"
	WorkersDir string
}

Manager handles creating and tearing down worktrees.

func NewManager

func NewManager() *Manager

NewManager creates a Manager with default settings.

func (*Manager) Create

func (m *Manager) Create(ctx context.Context, anvilPath, beadID string, branch ...string) (*Worktree, error)

Create creates a new worktree for the given bead in the given anvil directory. If branch is provided, it checks out that existing branch. Otherwise, it creates a new branch named forge/<bead-id> from origin/main or origin/master (whichever exists, resolved by resolveBaseRef).

func (*Manager) CreateEpicBranch

func (m *Manager) CreateEpicBranch(ctx context.Context, anvilPath, branchName string) error

CreateEpicBranch creates or verifies an epic feature branch from main and pushes it to origin. This is used when an epic bead is first picked up — the branch is created without any code changes so child beads can branch from it.

func (*Manager) CreateWithOptions

func (m *Manager) CreateWithOptions(ctx context.Context, anvilPath, beadID string, opts CreateOptions) (*Worktree, error)

CreateWithOptions creates a new worktree with full control over branch and base ref. When opts.BaseBranch is set, the worktree branches from origin/<BaseBranch> instead of origin/main.

func (*Manager) FetchBranch

func (m *Manager) FetchBranch(ctx context.Context, anvilPath, branchName string) error

FetchBranch fetches a single named branch from origin in the given anvil directory, updating the local remote-tracking ref. This is the canonical way for daemon code to fetch a branch without going through a full worktree create/reset cycle.

func (*Manager) List

func (m *Manager) List(anvilPath string) ([]string, error)

List returns the paths of all active worktrees under .workers/ for an anvil.

func (*Manager) Remove

func (m *Manager) Remove(ctx context.Context, anvilPath string, wt *Worktree) error

Remove tears down a worktree and cleans up its branch.

type Worktree

type Worktree struct {
	// BeadID is the bead being worked on.
	BeadID string
	// AnvilPath is the root of the source repository.
	AnvilPath string
	// Path is the absolute path to the worktree directory.
	Path string
	// Branch is the git branch name.
	Branch string
	// BaseBranch is the branch this worktree was branched from.
	// Empty means the default (main/master).
	BaseBranch string
}

Worktree represents an active git worktree for a Smith worker.