worktree

package
v0.0.321 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 10, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package worktree manages git worktrees for term-llm sessions.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrDirty     = errors.New("worktree has uncommitted changes")
	ErrExists    = errors.New("worktree already exists")
	ErrConflict  = errors.New("merge back has conflicts")
	ErrRootDirty = errors.New("root checkout has uncommitted changes")
)

Functions

func Diff 

func Diff(dir string) (string, error)

Diff returns a unified diff from the recorded base and includes untracked files.

func IsGitRepo 

func IsGitRepo(dir string) bool

IsGitRepo reports whether dir is inside a git working tree.

func MainRepoRoot 

func MainRepoRoot(dir string) (string, error)

MainRepoRoot returns the canonical main checkout root for any worktree in the repo.

func ManagedRoot 

func ManagedRoot(repoRoot string) (string, error)

ManagedRoot returns the bucket for managed worktrees for repoRoot.

func ManagedRootBase 

func ManagedRootBase() (string, error)

ManagedRootBase returns the global worktree data directory.

func Promote 

func Promote(ctx context.Context, dir, branch string) error

Promote creates a branch at the worktree HEAD and checks it out.

func Remove 

func Remove(ctx context.Context, dir string, opts RemoveOptions) error

Remove removes a managed worktree and prunes git's worktree metadata.

func TouchLastBound 

func TouchLastBound(dir string) error

TouchLastBound records that a session bound this worktree now.

Types

type AssistedMergeOptions 

type AssistedMergeOptions struct {
	Branch         string
	SnapshotCommit string
	Message        string
}

AssistedMergeOptions configures StartAssistedMerge.

type AssistedMergeResult 

type AssistedMergeResult struct {
	RootDir            string   `json:"root_dir,omitempty"`
	WorktreeDir        string   `json:"worktree_dir,omitempty"`
	WorktreeName       string   `json:"worktree_name,omitempty"`
	Branch             string   `json:"branch,omitempty"`
	PreviousRootRef    string   `json:"previous_root_ref,omitempty"`
	PreviousRootBranch string   `json:"previous_root_branch,omitempty"`
	Base               string   `json:"base,omitempty"`
	RootHead           string   `json:"root_head,omitempty"`
	WorktreeHead       string   `json:"worktree_head,omitempty"`
	SnapshotCommit     string   `json:"snapshot_commit,omitempty"`
	ChangedFiles       []string `json:"changed_files,omitempty"`
	Conflicts          []string `json:"conflicts,omitempty"`
	RootStatus         string   `json:"root_status,omitempty"`
	Applied            bool     `json:"applied"`
	NeedsResolution    bool     `json:"needs_resolution"`
	Message            string   `json:"message,omitempty"`
}

AssistedMergeResult describes a recovery branch prepared for LLM-assisted merge resolution.

func StartAssistedMerge 

func StartAssistedMerge(ctx context.Context, dir string, opts AssistedMergeOptions) (AssistedMergeResult, error)

StartAssistedMerge prepares a safe root recovery branch for LLM-assisted resolution. It applies the worktree snapshot with cherry-pick -n and leaves conflicts in place on the recovery branch when they occur.

type CreateOptions 

type CreateOptions struct {
	Name         string
	Base         string
	Branch       string
	SetupScript  string
	SetupTimeout time.Duration
	CopyFiles    []string
	ProgressFn   func(message string)
	Progress     chan<- Progress
}

CreateOptions configures Create.

type InUseSession 

type InUseSession struct {
	ID     string `json:"id"`
	Number int64  `json:"number,omitempty"`
	Name   string `json:"name,omitempty"`
	Status string `json:"status,omitempty"`
}

InUseSession describes a session bound to a worktree.

func InUse 

func InUse(ctx context.Context, store session.Store, dir string) ([]InUseSession, error)

InUse returns non-archived sessions currently bound to dir when the store exposes worktree summaries.

type MergeOptions 

type MergeOptions struct {
	AllowDirty bool
	Commit     bool
	Message    string
}

MergeOptions configures MergeBack.

type MergeResult 

type MergeResult struct {
	Applied              bool     `json:"applied"`
	Committed            bool     `json:"committed"`
	SnapshotCommit       string   `json:"snapshot_commit,omitempty"`
	Conflicts            []string `json:"conflicts,omitempty"`
	Message              string   `json:"message,omitempty"`
	WorktreeDir          string   `json:"worktree_dir,omitempty"`
	RootDir              string   `json:"root_dir,omitempty"`
	WorktreeName         string   `json:"worktree_name,omitempty"`
	Base                 string   `json:"base,omitempty"`
	WorktreeHead         string   `json:"worktree_head,omitempty"`
	RootHead             string   `json:"root_head,omitempty"`
	RootStatus           string   `json:"root_status,omitempty"`
	ChangedFiles         []string `json:"changed_files,omitempty"`
	ConflictReset        bool     `json:"conflict_reset,omitempty"`
	ConflictCleanupError string   `json:"conflict_cleanup_error,omitempty"`
}

MergeResult describes the result of MergeBack.

func MergeBack 

func MergeBack(ctx context.Context, dir string, opts MergeOptions) (MergeResult, error)

MergeBack snapshots the worktree and cherry-picks it into the root checkout staged and uncommitted by default.

type Progress 

type Progress struct {
	Message string `json:"message"`
}

Progress is emitted by long-running worktree operations.

type PromoteOptions 

type PromoteOptions struct {
	Message string
}

PromoteOptions configures PromoteToRoot.

type PromoteResult 

type PromoteResult struct {
	RootDir                     string   `json:"root_dir,omitempty"`
	WorktreeDir                 string   `json:"worktree_dir,omitempty"`
	WorktreeName                string   `json:"worktree_name,omitempty"`
	Branch                      string   `json:"branch,omitempty"`
	PreviousRootRef             string   `json:"previous_root_ref,omitempty"`
	PreviousRootBranch          string   `json:"previous_root_branch,omitempty"`
	WorktreeHead                string   `json:"worktree_head,omitempty"`
	SnapshotCommit              string   `json:"snapshot_commit,omitempty"`
	ChangedFiles                []string `json:"changed_files,omitempty"`
	RootStatus                  string   `json:"root_status,omitempty"`
	Applied                     bool     `json:"applied"`
	OriginalWorktreeStillExists bool     `json:"original_worktree_still_exists"`
}

PromoteResult describes the result of PromoteToRoot.

func PromoteToRoot 

func PromoteToRoot(ctx context.Context, dir, branch string, opts PromoteOptions) (PromoteResult, error)

PromoteToRoot creates a branch from the worktree HEAD, checks it out in the root checkout, and applies dirty worktree changes there staged and uncommitted. The original linked worktree is left in place.

type RemoveOptions 

type RemoveOptions struct {
	Force        bool
	DeleteBranch bool
}

RemoveOptions configures Remove.

type Status 

type Status string

Status describes where a worktree is in its lifecycle. 

const (
	StatusCreating Status = "creating"
	StatusReady    Status = "ready"
	StatusFailed   Status = "failed"
)

type Worktree 

type Worktree struct {
	Name        string    `json:"name"`
	Dir         string    `json:"dir"`
	RepoRoot    string    `json:"repo_root,omitempty"`
	Branch      string    `json:"branch,omitempty"`
	Base        string    `json:"base"` // full base SHA
	Detached    bool      `json:"detached"`
	Status      Status    `json:"status"`
	DirtyFiles  int       `json:"dirty_files"`
	HeadSHA     string    `json:"head_sha"`
	CreatedAt   time.Time `json:"created_at,omitempty"`
	LastBoundAt time.Time `json:"last_bound_at,omitempty"`
	Orphaned    bool      `json:"orphaned,omitempty"`
}

Worktree describes a managed git worktree.

func Create 

func Create(ctx context.Context, repoRoot string, opts CreateOptions) (*Worktree, error)

Create creates a managed worktree. Detached HEAD is used unless Branch is set.

func Get 

func Get(dir string) (*Worktree, error)

Get describes a worktree by directory.

func List 

func List(repoRoot string) ([]Worktree, error)

List returns managed worktrees for the repository, excluding the main checkout.

func ListAll 

func ListAll() ([]Worktree, error)

ListAll scans all managed buckets using metadata. Orphaned buckets are marked.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.