worktree

Documentation

Overview

Package worktree — see worktree.go for the package overview.

Package worktree manages the dedicated git worktree used by `ktn-linter skill comments`. The lifecycle is:

1. Create - `git worktree add` on a fresh branch.
2. Run - the caller spawns its tool inside Path.
3. Finish - SquashMerge or Keep + Cleanup remove the worktree.

The package never runs destructive git commands implicitly; if the worktree contains uncommitted work, Cleanup refuses to drop it unless the caller passes Force.

Index

• Variables
• type CreateOptions
• type State
  • func Create(ctx context.Context, opts CreateOptions) (state *State, err error)
  • func (w *State) Cleanup(ctx context.Context, force bool) error
  • func (w *State) CommitAll(ctx context.Context, commitMessage string) error
  • func (w *State) SquashMerge(ctx context.Context, message string) error

Variables

var (
	// ErrDirtyWorktree is returned when Cleanup runs on a worktree that
	// still has uncommitted edits and force is not set.
	ErrDirtyWorktree = errors.New(
		"worktree: refused to clean up: uncommitted changes present (pass force=true to drop)")

	// ErrDetachedHEAD is returned when Create is invoked outside any
	// branch; SquashMerge would have nowhere to land.
	ErrDetachedHEAD = errors.New(
		"worktree: refusing to run from a detached HEAD; check out a branch first")
)

: Refusing destructive operations is the package's safety contract. : Sentinels let callers branch on the exact refusal cause without : parsing message strings.

Types

type CreateOptions

type CreateOptions struct {
	// RepoRoot is the source repository (defaults to the cwd-resolved
	// `git rev-parse --show-toplevel`).
	RepoRoot string

	// Name overrides the auto-generated worktree directory name. The
	// branch name follows the same suffix.
	Name string
}

CreateOptions controls the worktree directory + branch naming. RepoRoot defaults to the cwd-resolved git toplevel; Name overrides the auto-generated worktree directory and the branch suffix.

type State

type State struct {
	// RepoRoot is the absolute path of the source repository.
	RepoRoot string

	// Path is the absolute path of the temporary worktree directory.
	Path string

	// Branch is the name of the throwaway branch checked out in Path.
	Branch string

	// SourceBranch is the branch the caller was on at Create time;
	// SquashMerge folds Branch back into it.
	SourceBranch string
}

State describes a temporary git worktree backing a single skill run. The struct is created by Create and consumed by SquashMerge / Cleanup.

func Create

func Create(ctx context.Context, opts CreateOptions) (state *State, err error)

Create initialises a fresh worktree under <RepoRoot>/.<Name> on a branch named ktn-comments/<Name>. When Name is empty it falls back to a timestamped slug.

func (*State) Cleanup

func (w *State) Cleanup(ctx context.Context, force bool) error

Cleanup removes the worktree directory and its branch. force=false refuses to remove a worktree that still has uncommitted changes or commits not yet folded into SourceBranch.

func (*State) CommitAll

func (w *State) CommitAll(ctx context.Context, commitMessage string) error

CommitAll stages and commits every worktree edit. A no-op when the worker left a clean tree (claude already committed). Without this, subsequent SquashMerge would fold *zero* changes back to SourceBranch because uncommitted edits don't enter `git merge`.

The commit is created with message `commitMessage`; the tree is committed only if there is something to stage.

func (*State) SquashMerge

func (w *State) SquashMerge(ctx context.Context, message string) error

SquashMerge folds every commit on State.Branch back into State.SourceBranch as a single squash commit, then removes the worktree and the temporary branch. message is the squash commit subject.