worktree

Documentation

Overview

Package worktree provides WIP (Work-In-Progress) handling utilities.

Index

• func DeriveWorktreeName(branch, strategy string) string
• func TestEnvNumber(name string) int
• func TmuxSessionName(project, worktreeName string) string
• type DirtyAction
  • func ResolveDirtyAction(dirtyHandling string, isDirty, isPeek, isInteractive bool) DirtyAction
• type Manager
  • func NewManager(repoRoot string) (*Manager, error)
  • func (m *Manager) Create(name, branch string) error
  • func (m *Manager) CreateFromBranch(name, branch string) error
  • func (m *Manager) CreateFromExisting(name, branch string) error
  • func (m *Manager) CreateFromRef(name, branch, fromRef string) error
  • func (m *Manager) Find(name string) (*Worktree, error)
  • func (m *Manager) FullName(name string) string
  • func (m *Manager) GetCommitInfo(path string) (shortHash, message, age string, err error)
  • func (m *Manager) GetCurrent() (*Worktree, error)
  • func (m *Manager) GetDirtyFiles(path string) (string, error)
  • func (m *Manager) GetProjectName() string
  • func (m *Manager) GetRepoRoot() string
  • func (m *Manager) List() ([]*Worktree, error)
  • func (m *Manager) Move(oldName, newName string) error
  • func (m *Manager) Remove(name string) error
• type WIPHandler
  • func NewWIPHandler(repoPath string) *WIPHandler
  • func (h *WIPHandler) ApplyPatch(patch []byte) error
  • func (h *WIPHandler) CreatePatch() ([]byte, error)
  • func (h *WIPHandler) HasStagedChanges() (bool, error)
  • func (h *WIPHandler) HasUnstagedChanges() (bool, error)
  • func (h *WIPHandler) HasUntrackedFiles() (bool, error)
  • func (h *WIPHandler) HasWIP() (bool, error)
  • func (h *WIPHandler) ListWIPFiles() ([]string, error)
  • func (h *WIPHandler) PopStash() error
  • func (h *WIPHandler) Stash(message string) error
• type Worktree
  • func (w *Worktree) DisplayName() string

Functions

func DeriveWorktreeName

func DeriveWorktreeName(branch, strategy string) string

DeriveWorktreeName derives a suggested worktree name from a branch name. Strategy "last_segment" (default) takes the part after the last "/". E.g., "feat/agent-slot-db" → "agent-slot-db", "main" → "main".

func TestEnvNumber

func TestEnvNumber(name string) int

TestEnvNumber derives a stable TEST_ENV_NUMBER in range [50, 99] from a worktree name. The same name always produces the same number (deterministic via MD5 hash).

func TmuxSessionName

func TmuxSessionName(project, worktreeName string) string

TmuxSessionName returns the tmux session name for a worktree. The main/root worktree uses just the project name (e.g. "myapp"), while branch worktrees use project-name (e.g. "myapp-testing").

Types

type DirtyAction

type DirtyAction int

DirtyAction represents the resolved action to take when the current worktree has uncommitted changes.

const (
	DirtyAllow  DirtyAction = iota // Proceed with switch
	DirtyStash                     // Auto-stash changes before switching
	DirtyPrompt                    // Ask the user interactively
	DirtyRefuse                    // Block the switch
)

func ResolveDirtyAction

func ResolveDirtyAction(dirtyHandling string, isDirty, isPeek, isInteractive bool) DirtyAction

ResolveDirtyAction determines what to do when switching away from a worktree based on the configured dirty handling mode, current state, and environment.

type Manager

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

Manager handles git worktree operations

func NewManager

func NewManager(repoRoot string) (*Manager, error)

NewManager creates a new worktree manager If repoRoot is empty, it will detect from current directory

func (*Manager) Create

func (m *Manager) Create(name, branch string) error

Create creates a new worktree with a new branch from HEAD. The name parameter is the short name (e.g., "testing") The directory will be created with the full name including project prefix

func (*Manager) CreateFromBranch

func (m *Manager) CreateFromBranch(name, branch string) error

CreateFromBranch creates a worktree from a branch (local or remote). For remote branches (e.g., PR branches), it fetches and checks out the branch. The name parameter is the short name (e.g., "pr-123-fix-bug")

func (*Manager) CreateFromExisting

func (m *Manager) CreateFromExisting(name, branch string) error

CreateFromExisting creates a worktree from an existing branch The name parameter is the short name (e.g., "testing") The directory will be created with the full name including project prefix

func (*Manager) CreateFromRef

func (m *Manager) CreateFromRef(name, branch, fromRef string) error

CreateFromRef creates a new worktree with a new branch starting from a specific ref. The name parameter is the short name (e.g., "testing") The branch parameter is the new branch name to create. The fromRef parameter is the starting point (e.g., "develop", "origin/main", a commit SHA). If fromRef is empty, the worktree is created from HEAD.

func (*Manager) Find

func (m *Manager) Find(name string) (*Worktree, error)

Find searches for a worktree by short name or full name Returns the worktree if found, nil if not found

func (*Manager) FullName

func (m *Manager) FullName(name string) string

FullName returns the full worktree name with project prefix. Format: {project}-{name} Example: grove-cli-testing

func (*Manager) GetCommitInfo

func (m *Manager) GetCommitInfo(path string) (shortHash, message, age string, err error)

GetCommitInfo retrieves detailed commit information for a worktree.

func (*Manager) GetCurrent

func (m *Manager) GetCurrent() (*Worktree, error)

GetCurrent returns the current worktree

func (*Manager) GetDirtyFiles

func (m *Manager) GetDirtyFiles(path string) (string, error)

GetDirtyFiles returns the list of dirty files from git status.

func (*Manager) GetProjectName

func (m *Manager) GetProjectName() string

GetProjectName returns the project name for the repository

func (*Manager) GetRepoRoot

func (m *Manager) GetRepoRoot() string

GetRepoRoot returns the repository root path

func (*Manager) List

func (m *Manager) List() ([]*Worktree, error)

List returns all worktrees in the repository

func (*Manager) Move

func (m *Manager) Move(oldName, newName string) error

Move renames a worktree directory using git worktree move. Both oldName and newName are short names (without project prefix).

func (*Manager) Remove

func (m *Manager) Remove(name string) error

Remove removes a worktree

type WIPHandler

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

WIPHandler handles work-in-progress detection and manipulation.

func NewWIPHandler

func NewWIPHandler(repoPath string) *WIPHandler

NewWIPHandler creates a new WIP handler for the given repository path.

func (*WIPHandler) ApplyPatch

func (h *WIPHandler) ApplyPatch(patch []byte) error

ApplyPatch applies a patch to the working tree.

func (*WIPHandler) CreatePatch

func (h *WIPHandler) CreatePatch() ([]byte, error)

CreatePatch creates a patch file from all uncommitted changes (staged and unstaged).

func (*WIPHandler) HasStagedChanges

func (h *WIPHandler) HasStagedChanges() (bool, error)

HasStagedChanges checks if there are any staged changes.

func (*WIPHandler) HasUnstagedChanges

func (h *WIPHandler) HasUnstagedChanges() (bool, error)

HasUnstagedChanges checks if there are any unstaged changes in tracked files.

func (*WIPHandler) HasUntrackedFiles

func (h *WIPHandler) HasUntrackedFiles() (bool, error)

HasUntrackedFiles checks if there are any untracked files.

func (*WIPHandler) HasWIP

func (h *WIPHandler) HasWIP() (bool, error)

HasWIP checks if there are any uncommitted changes (staged or unstaged).

func (*WIPHandler) ListWIPFiles

func (h *WIPHandler) ListWIPFiles() ([]string, error)

ListWIPFiles returns a list of files with uncommitted changes.

func (*WIPHandler) PopStash

func (h *WIPHandler) PopStash() error

PopStash applies and removes the most recent stash entry.

func (*WIPHandler) Stash

func (h *WIPHandler) Stash(message string) error

Stash saves uncommitted changes to the stash with the given message.

type Worktree

type Worktree struct {
	Name             string // Short name (derived from path)
	Path             string // Absolute path to worktree
	Branch           string // Branch name or "detached"
	Commit           string // Commit hash (full)
	ShortCommit      string // Short commit hash (7 chars)
	CommitMessage    string // Commit message subject
	CommitAge        string // Relative commit time
	IsDirty          bool   // Whether there are uncommitted changes
	DirtyCheckFailed bool   // Whether the dirty check errored (status unknown)
	DirtyFiles       string // List of dirty files (from git status --porcelain)
	IsMain           bool   // Whether this is the main worktree
	ShortName        string // Short name without project prefix
	IsPrunable       bool   // Whether the worktree directory is missing (stale)
}

Worktree represents a git worktree

func (*Worktree) DisplayName

func (w *Worktree) DisplayName() string

DisplayName returns the display name for a worktree Root worktree returns "root", others return short name without project prefix