worktree

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Sep 23, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrWorktreeDirty means removal would discard local file changes.
	ErrWorktreeDirty = errors.New("refusing to remove worktree with local changes")
	// ErrWorktreeActive means a supported coding agent is running in the worktree.
	ErrWorktreeActive = errors.New("refusing to remove worktree with a running agent")
)
View Source 
var GitMu sync.Mutex

GitMu serializes git worktree operations to prevent concurrent index.lock conflicts.

Functions

func AgeDays 

func AgeDays(path string) (int, error)

AgeDays returns the age of a worktree in days based on its last commit.

func AgeHours 

func AgeHours(path string) (int, error)

AgeHours returns the age of a worktree in hours based on its last commit.

func CleanAllStaleLocks 

func CleanAllStaleLocks(cfg *config.Config)

CleanAllStaleLocks cleans stale locks across all known repos.

func CleanStaleLocks 

func CleanStaleLocks(cfg *config.Config, repo string)

CleanStaleLocks removes stale index.lock files from worktrees of the given repo. A lock is considered stale if the PID inside it is no longer running.

func CleanupFailedAdd added in v0.7.0 

func CleanupFailedAdd(originPath, worktreePath, branch string)

CleanupFailedAdd cleans up after a failed "git worktree add" that may have created the branch and/or a partial worktree directory but failed to complete (e.g., "Could not write new index file"). It removes the partial worktree directory, prunes git's worktree metadata, and deletes the orphaned branch.

originPath is the main repo directory, worktreePath is the target worktree directory, and branch is the git branch that was being created.

func CreateFromMain added in v0.11.0 

func CreateFromMain(originPath, worktreePath, worktreeName, branch string) error

CreateFromMain fetches origin/main and creates a new worktree checked out to a new branch cut from it. Used for feature work (branch didn't exist before), as opposed to PR review worktrees which check out an existing remote branch/ref instead.

Uses --no-checkout + a separate checkout to avoid "Could not write new index file" on large repos (13K+ files) — the two-step approach handles the index write reliably. Serializes on GitMu to prevent concurrent index.lock conflicts across worktree operations on the same origin repo.

func CreateFromPR added in v0.11.0 

func CreateFromPR(originPath, worktreePath, worktreeName string, prNumber int) error

CreateFromPR fetches the PR's remote branch (pull/N/head) into a local pr-N branch and creates a worktree checked out to it. Used for PR review worktrees, which check out an existing remote ref, as opposed to CreateFromMain which cuts a brand new branch for feature work.

If worktreePath already exists by the time the lock is acquired (e.g. a concurrent caller created it first), this is a no-op — callers that need a fast pre-lock existence check too (to skip the wait entirely in the common case) can still do their own os.Stat before calling.

Uses --no-checkout + a separate checkout to avoid "Could not write new index file" on large repos (13K+ files) — the two-step approach handles the index write reliably. Serializes on GitMu to prevent concurrent index.lock conflicts across worktree operations on the same origin repo.

func FastForward added in v0.12.0 

func FastForward(ctx context.Context, worktreePath string, prNumber int) error

FastForward fast-forwards the worktree onto refs/remotes/origin/pr-N. A non-ff merge returns *ErrNonFastForward. Callers that want the worktree to match GitHub anyway should ResetToRemotePR when the tree is clean.

func FetchPRHead added in v0.12.0 

func FetchPRHead(ctx context.Context, originPath string, prNumber int) error

FetchPRHead fetches GitHub's pull/N/head into refs/remotes/origin/pr-N.

func FetchRefspec added in v0.12.0 

func FetchRefspec(ctx context.Context, originPath, refspec string) error

FetchRefspec runs `git fetch origin <refspec>` in originPath. 

func HEAD(worktreePath string) (string, error)

HEAD returns the full SHA of HEAD in the given working tree.

func IsMissingPRRef added in v0.12.0 

func IsMissingPRRef(err error) bool

IsMissingPRRef reports whether git fetch failed because pull/N/head is gone (PR deleted, or GitHub no longer advertises the ref). Callers should skip, not retry as a git flake.

func IsNonFastForward added in v0.12.0 

func IsNonFastForward(err error) bool

IsNonFastForward reports whether err is a rejected fast-forward.

func LastActivity 

func LastActivity(path string) (time.Time, error)

LastActivity returns the date of the last commit in the worktree.

func PRName added in v0.12.0 

func PRName(repoShort string, prNumber int) string

PRName is the directory name of a PR review worktree: <repo>-pr-<number>. Every caller goes through here so the layout has one definition to change.

func PRPath added in v0.12.0 

func PRPath(basePath, repoShort string, prNumber int) string

PRPath is where a PR review worktree for repoShort lives under basePath.

func ParseBranchFromName 

func ParseBranchFromName(name string) string

ParseBranchFromName extracts the branch suffix from a worktree directory name. e.g., "mono-feature-branch" -> "feature-branch"

func ParseRepoFromName 

func ParseRepoFromName(name string) string

ParseRepoFromName extracts the repo short name from a worktree directory name. e.g., "mono-pr-1234" -> "mono"

func RemotePRRef added in v0.12.0 

func RemotePRRef(prNumber int) string

RemotePRRef is the remote-tracking ref used to store pull/N/head. Fetching into the local pr-N branch is refused when that branch is checked out in a worktree; this ref is never checked out.

func RemovalBlocked added in v0.12.0 

func RemovalBlocked(err error) bool

RemovalBlocked reports whether err is an expected safety refusal rather than a Git or filesystem failure.

func Remove added in v0.12.0 

func Remove(originPath, worktreePath string) error

Remove removes a linked worktree only when it is inactive and contains no local changes. Zen-generated review context is reproducible and does not make a worktree dirty. A missing worktree is already removed and succeeds.

func RemoveStaleLock added in v0.7.0 

func RemoveStaleLock(lockFile, name string)

RemoveStaleLock removes an index.lock file only if the holding process is no longer running. Safe to call if the file does not exist.

func ResetToRemotePR added in v0.12.0 

func ResetToRemotePR(ctx context.Context, worktreePath string, prNumber int) error

ResetToRemotePR points the worktree at refs/remotes/origin/pr-N with reset --hard. Used after a non-fast-forward fetch (force-push) when the tree has no tracked local changes and the user confirmed. Untracked files (CLAUDE.local.md, .zen/) are left in place. The previous tip remains in the reflog as pr-N@{1}.

func RevParse added in v0.12.0 

func RevParse(worktreePath, rev string) (string, error)

RevParse resolves a revision in worktreePath.

func SHAEqual added in v0.12.0 

func SHAEqual(a, b string) bool

SHAEqual reports whether two git object names refer to the same commit. Empty strings never match. Short prefixes of at least 7 hex chars match a longer SHA.

func TrackedDirty added in v0.12.0 

func TrackedDirty(worktreePath string) (bool, error)

TrackedDirty reports whether worktreePath has staged or unstaged changes to tracked files. Untracked files (CLAUDE.local.md, AGENTS.md, .zen/) are ignored so injected context does not block a fast-forward.

func UniqueCommitCount added in v0.12.0 

func UniqueCommitCount(worktreePath string, prNumber int) (int, error)

UniqueCommitCount is how many commits are on HEAD that are not in refs/remotes/origin/pr-N. Used to warn before reset --hard: a linear GitHub update with no local commits is 0; a local review commit or a rewritten remote is typically ≥1.

Types

type ErrNonFastForward added in v0.12.0 

type ErrNonFastForward struct {
	Detail string
}

ErrNonFastForward is returned when a worktree cannot be fast-forwarded (diverged history, typically a force-push). Callers should ResetToRemotePR when the worktree is clean and idle, not skip forever.

func (*ErrNonFastForward) Error added in v0.12.0 

func (e *ErrNonFastForward) Error() string

type Stats 

type Stats struct {
	Total     int            `json:"total"`
	PRReviews int            `json:"pr_reviews"`
	Features  int            `json:"features"`
	ByRepo    map[string]int `json:"by_repo"`
}

Stats holds worktree statistics.

func GetStats 

func GetStats(cfg *config.Config) (*Stats, error)

GetStats computes statistics across all worktrees.

type Type 

type Type string

Type classifies a worktree. 

const (
	TypePRReview Type = "pr-review"
	TypeFeature  Type = "feature"
)

func Classify 

func Classify(name string) (Type, int)

Classify determines if a worktree name represents a PR review or feature work.

type Worktree 

type Worktree struct {
	Path     string `json:"path"`
	Name     string `json:"name"`
	Branch   string `json:"branch"`
	Type     Type   `json:"type"`
	PRNumber int    `json:"pr_number,omitempty"`
	Repo     string `json:"repo"`
}

Worktree represents a discovered git worktree.

func ListAll 

func ListAll(cfg *config.Config) ([]Worktree, error)

ListAll lists worktrees across all configured repositories.

func ListForRepo 

func ListForRepo(cfg *config.Config, repo string) ([]Worktree, error)

ListForRepo lists all worktrees for a given repository using `git worktree list`.

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.