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 CurrentBranch(ctx context.Context, repoPath string) (string, error)
- func VerifyAndRecoverMain(ctx context.Context, repoPath string) (recovered bool, originalBranch string, err error)
- type CreateOptions
- type 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) List(anvilPath string) ([]string, error)
- func (m *Manager) Remove(ctx context.Context, anvilPath string, wt *Worktree) error
- type Worktree
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CurrentBranch ¶ added in v0.4.0
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 VerifyAndRecoverMain ¶ added in v0.4.0
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
}
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 (*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 ¶
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.
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.
Source Files