worktree

Documentation

Overview

Package worktree provides git-worktree management via shell commands. It uses exec.Command("git", ...) — no go-git dependency.

Index

• Variables
• type BranchLock
  • func NewBranchLock() *BranchLock
  • func (b *BranchLock) Acquire(ctx context.Context, branch string) (release func(), err error)
  • func (b *BranchLock) TryAcquire(branch string) (release func(), err error)
• type BranchLocker
• type Manager
  • func NewManager(projectRoot string) *Manager
  • func (m *Manager) Create(ctx context.Context, branch, baseRev string) (Worktree, error)
  • func (m *Manager) List(ctx context.Context) ([]Worktree, error)
  • func (m *Manager) Prune(ctx context.Context) error
  • func (m *Manager) Remove(ctx context.Context, branch string, force bool) error
  • func (m *Manager) Status(ctx context.Context, branch string) (Worktree, error)
• type Worktree

Variables

var (
	ErrInvalidBranch = errors.New("invalid branch name")
	ErrAlreadyExists = errors.New("worktree directory already exists")
)

Sentinel errors.

var ErrBranchBusy = errors.New("branch is in use by another worktree session")

ErrBranchBusy is returned by TryAcquire when the branch is already locked.

Types

type BranchLock

type BranchLock struct {
	// contains filtered or unexported fields
}

BranchLock provides in-process mutual exclusion by branch name. Acquire blocks until the lock is available; TryAcquire returns immediately with ErrBranchBusy if held. Both return a release function. Release is idempotent — calling it multiple times is a no-op. BranchLock is NOT reentrant: calling Acquire twice on the same branch from the same goroutine will deadlock.

Lock ownership is transferred directly from one holder to the next waiter without an unlocked window, so TryAcquire cannot interpose between a release and the queued waiter acquiring.

func NewBranchLock

func NewBranchLock() *BranchLock

NewBranchLock creates a new, empty BranchLock.

func (*BranchLock) Acquire

func (b *BranchLock) Acquire(ctx context.Context, branch string) (release func(), err error)

Acquire blocks until the given branch is available or ctx is cancelled. Returns a release function that must be called exactly once to unlock.

func (*BranchLock) TryAcquire

func (b *BranchLock) TryAcquire(branch string) (release func(), err error)

TryAcquire attempts to acquire the lock non-blockingly. Returns ErrBranchBusy if the branch is already locked.

type BranchLocker

type BranchLocker interface {
	Acquire(ctx context.Context, branch string) (release func(), err error)
	TryAcquire(branch string) (release func(), err error)
}

BranchLocker is the narrow interface for branch-level mutual exclusion. Implemented by *BranchLock.

type Manager

type Manager struct {
	Root string // project root; worktrees go to <Root>/.deepseek/worktrees/
}

Manager manages git worktrees under a project root.

func NewManager

func NewManager(projectRoot string) *Manager

NewManager returns a Manager for the given project root.

func (*Manager) Create

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

Create creates a new worktree with the given branch name, based on baseRev. Equivalent to: git worktree add -b <branch> <Root>/.deepseek/worktrees/<branch> <baseRev>

func (*Manager) List

func (m *Manager) List(ctx context.Context) ([]Worktree, error)

List returns all worktrees for this repository, including the main worktree. Parses `git worktree list --porcelain`.

func (*Manager) Prune

func (m *Manager) Prune(ctx context.Context) error

Prune runs `git worktree prune -v` to remove stale worktree entries.

func (*Manager) Remove

func (m *Manager) Remove(ctx context.Context, branch string, force bool) error

Remove removes a worktree by branch name. If force is true, uses --force.

func (*Manager) Status

func (m *Manager) Status(ctx context.Context, branch string) (Worktree, error)

Status returns the current status of a worktree by branch name. Combines `git worktree list --porcelain` (for locked) with `git -C <path> status --porcelain` (for dirty/clean).

type Worktree

type Worktree struct {
	Branch string // branch name (e.g. "feat/x")
	Path   string // absolute filesystem path
	Head   string // commit SHA at HEAD
	Locked bool   // whether git reports this worktree as locked
	Dirty  bool   // whether git status --porcelain reports uncommitted changes
}

Worktree represents a single git worktree.