worktrees

Documentation

Overview

Package worktrees discovers Git worktrees without mutating repositories.

Index

• Variables
• func Contains(worktreePath, cwd string) bool
• type CreateResult
• type Manager
  • func NewManager(git Runner, storePath, managedRoot string) (*Manager, error)
  • func (m *Manager) ApplySessions(result *Result)
  • func (m *Manager) Create(source, branch, baseRef string) (CreateResult, error)
  • func (m *Manager) CreateWithReadyBinding(source, branch, baseRef string, bind func(CreateResult)) (CreateResult, error)
  • func (m *Manager) Discover(cwd string) (Result, error)
  • func (m *Manager) DiscoverAllManagedRepositories() Result
  • func (m *Manager) ManagedBindingForPath(cwd string) (string, bool)
  • func (m *Manager) ReadOnly() bool
  • func (m *Manager) ReconcileAll() error
  • func (m *Manager) Record(id string) (Record, bool)
  • func (m *Manager) Records() []Record
  • func (m *Manager) Remove(id string, liveSessionIDs func() []string) error
  • func (m *Manager) Reserve(commonDir, repoRoot, branch, baseRef string) (Record, error)
  • func (m *Manager) RollbackCreated(id string) error
  • func (m *Manager) Transition(id string, expected, next State) error
  • func (m *Manager) WithReadyBinding(id, cwd string, operation func(canonicalPath string) error) error
  • func (m *Manager) WithRepository(commonDir string, operation func() error) error
• type Overview
  • func ParsePorcelain(data []byte, commonDir string) []Overview
• type Record
• type Result
  • func Discover(git Runner, cwd string) (Result, error)
• type Runner
• type State
• type Store
  • func NewStore(path string) *Store
  • func (s *Store) Load() ([]Record, error)
  • func (s *Store) Save(records []Record) error

Variables

var (
	ErrInvalidRef       = errors.New("worktrees: invalid ref")
	ErrBranchExists     = errors.New("worktrees: branch exists")
	ErrBranchCheckedOut = errors.New("worktrees: branch checked out")
	ErrRecoveryRequired = errors.New("worktrees: recovery required")
	ErrNotFound         = errors.New("worktrees: not found")
	ErrNotManaged       = errors.New("worktrees: not managed")
	ErrMain             = errors.New("worktrees: main worktree")
	ErrDirty            = errors.New("worktrees: dirty")
	ErrInUse            = errors.New("worktrees: in use")
	ErrLocked           = errors.New("worktrees: locked")
	ErrStatusUnknown    = errors.New("worktrees: status unknown")
	ErrIdentityChanged  = errors.New("worktrees: identity changed")
	ErrRemoveFailed     = errors.New("worktrees: remove failed")
)

var ErrCorruptStore = errors.New("worktrees: corrupt metadata")

var ErrDurabilityUncertain = errors.New("worktrees: replacement visible but directory sync failed")

var ErrFutureVersion = errors.New("worktrees: metadata version is newer than daemon")

var ErrNotRepository = errors.New("worktrees: not a repository")

var ErrPartial = errors.New("worktrees: status incomplete")

var ErrTooMany = errors.New("worktrees: result limit exceeded")

Functions

func Contains

func Contains(worktreePath, cwd string) bool

Contains reports whether cwd belongs to worktree after symlink resolution.

Types

type CreateResult

type CreateResult struct {
	Record       Record
	ResolvedBase string
}

type Manager

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

func NewManager

func NewManager(git Runner, storePath, managedRoot string) (*Manager, error)

func (*Manager) ApplySessions

func (m *Manager) ApplySessions(result *Result)

func (*Manager) Create

func (m *Manager) Create(source, branch, baseRef string) (CreateResult, error)

Create adds a daemon-owned worktree. All validation and mutation for one repository is serialized, while session creation remains outside this lock.

func (*Manager) CreateWithReadyBinding

func (m *Manager) CreateWithReadyBinding(source, branch, baseRef string, bind func(CreateResult)) (CreateResult, error)

CreateWithReadyBinding keeps the repository transaction locked through the initial session attachment callback, so removal cannot observe a ready zero-session gap between worktree creation and binding.

func (*Manager) Discover

func (m *Manager) Discover(cwd string) (Result, error)

func (*Manager) DiscoverAllManagedRepositories

func (m *Manager) DiscoverAllManagedRepositories() Result

DiscoverAllManagedRepositories returns fresh observations for every repository still referenced by trusted ownership metadata. This keeps zero-session managed worktrees visible for explicit reopen/removal.

func (*Manager) ManagedBindingForPath

func (m *Manager) ManagedBindingForPath(cwd string) (string, bool)

ManagedBindingForPath returns the trusted managed record containing cwd, including transitional records so a legacy request cannot race removal by omitting worktree_id.

func (*Manager) ReadOnly

func (m *Manager) ReadOnly() bool

func (*Manager) ReconcileAll

func (m *Manager) ReconcileAll() error

ReconcileAll checks each recorded repository once. It only updates provenance state; it never creates, removes, or force-cleans a worktree.

func (*Manager) Record

func (m *Manager) Record(id string) (Record, bool)

func (*Manager) Records

func (m *Manager) Records() []Record

func (*Manager) Remove

func (m *Manager) Remove(id string, liveSessionIDs func() []string) error

Remove deletes only the checkout of a currently clean, unused daemon-owned worktree. The branch and commits are deliberately left intact. Callers pass the live session IDs observed immediately before entry; all Git and path invariants are re-read after acquiring the repository lock.

func (*Manager) Reserve

func (m *Manager) Reserve(commonDir, repoRoot, branch, baseRef string) (Record, error)

func (*Manager) RollbackCreated

func (m *Manager) RollbackCreated(id string) error

RollbackCreated removes only a clean worktree produced by this manager.

func (*Manager) Transition

func (m *Manager) Transition(id string, expected, next State) error

func (*Manager) WithReadyBinding

func (m *Manager) WithReadyBinding(id, cwd string, operation func(canonicalPath string) error) error

WithReadyBinding serializes session attachment with worktree removal. The callback runs only while id still names the trusted ready checkout at cwd. It must stay short and must not perform Git I/O.

func (*Manager) WithRepository

func (m *Manager) WithRepository(commonDir string, operation func() error) error

type Overview

type Overview struct {
	ID            string    `json:"id"`
	Managed       bool      `json:"managed"`
	Path          string    `json:"path"`
	RepoRoot      string    `json:"repo_root"`
	Branch        string    `json:"branch,omitempty"`
	Head          string    `json:"head,omitempty"`
	Detached      bool      `json:"detached"`
	Locked        bool      `json:"locked"`
	Prunable      bool      `json:"prunable"`
	IsMain        bool      `json:"is_main"`
	Dirty         bool      `json:"dirty"`
	StatusKnown   bool      `json:"status_known"`
	StatusError   string    `json:"status_error,omitempty"`
	ChangeCount   int       `json:"change_count"`
	SessionIDs    []string  `json:"session_ids"`
	CanRemove     bool      `json:"can_remove"`
	RemoveBlocker string    `json:"remove_blocker,omitempty"`
	State         string    `json:"state,omitempty"`
	BindingHealth string    `json:"binding_health,omitempty"`
	CreatedAt     time.Time `json:"created_at,omitempty"`
	LastActivity  time.Time `json:"last_activity,omitempty"`
	Stale         bool      `json:"stale"`
}

func ParsePorcelain

func ParsePorcelain(data []byte, commonDir string) []Overview

type Record

type Record struct {
	ID                    string    `json:"id"`
	CommonDir             string    `json:"common_dir"`
	RepoRoot              string    `json:"repo_root"`
	Path                  string    `json:"path"`
	Branch                string    `json:"branch,omitempty"`
	BaseRef               string    `json:"base_ref,omitempty"`
	CreatedAt             time.Time `json:"created_at"`
	LastActivityAt        time.Time `json:"last_activity_at,omitempty"`
	LastDirtyTransitionAt time.Time `json:"last_dirty_transition_at,omitempty"`
	State                 State     `json:"state"`
}

type Result

type Result struct {
	RepoRoot  string     `json:"repo_root"`
	CommonDir string     `json:"-"`
	Partial   bool       `json:"partial"`
	Worktrees []Overview `json:"worktrees"`
}

func Discover

func Discover(git Runner, cwd string) (Result, error)

type Runner

type Runner interface {
	RunTimeout(cwd string, timeout time.Duration, args ...string) (*rgit.Result, error)
}

type State

type State string

const (
	StateReady            State = "ready"
	StateCreating         State = "creating"
	StateRemoving         State = "removing"
	StateRecoveryRequired State = "recovery_required"
)

type Store

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

func NewStore

func NewStore(path string) *Store

func (*Store) Load

func (s *Store) Load() ([]Record, error)

func (*Store) Save

func (s *Store) Save(records []Record) error