worktree

Documentation

Overview

Package worktree creates throwaway git worktrees so an agent can work in isolation from the user's checkout. The worktree shares the repository's object store but has its own working directory and branch, letting the user keep using the original checkout while the agent makes changes.

Index

• Variables
• type Status
  • func (s Status) IsDirty() bool
• type Worktree
  • func Create(ctx context.Context, dir, name string) (*Worktree, error)
  • func CreatePR(ctx context.Context, dir, ref string) (*Worktree, error)
  • func (wt *Worktree) Remove(ctx context.Context) error
  • func (wt *Worktree) Status(ctx context.Context) (Status, error)

Variables

var ErrGHNotFound = errors.New("the GitHub CLI (gh) is required to check out a pull request")

ErrGHNotFound means the GitHub CLI (gh) is required but not installed.

var ErrInvalidName = errors.New("invalid worktree name")

ErrInvalidName means the requested worktree name cannot be safely used as a directory and branch component.

var ErrInvalidPRRef = errors.New("invalid pull request reference")

ErrInvalidPRRef means a --worktree-pr value is not a PR number or URL.

var ErrNotGitRepository = errors.New("not a git repository")

ErrNotGitRepository means the requested directory is not inside a git worktree.

Types

type Status

type Status struct {
	// Modified is true when tracked files have uncommitted changes.
	Modified bool
	// Untracked is true when the worktree contains untracked files.
	Untracked bool
	// NewCommits is true when commits were added since the worktree was
	// created (HEAD moved away from [Worktree.BaseCommit]).
	NewCommits bool
}

Status describes whether a worktree holds work that would be lost if it were removed.

func (Status) IsDirty

func (s Status) IsDirty() bool

IsDirty reports whether the worktree holds any work (uncommitted changes, untracked files, or new commits) that removing it would discard.

type Worktree

type Worktree struct {
	// Dir is the absolute path of the worktree's working directory.
	Dir string
	// Branch is the branch checked out in the worktree.
	Branch string
	// Name is the worktree's name (the part after the "worktree-" branch prefix).
	Name string
	// SourceDir is the root of the repository the worktree was branched
	// from. The worktree lives under the data directory, far from the
	// original checkout, so setup hooks need this to copy untracked files
	// (.env, local config) git won't carry over.
	SourceDir string
	// BaseCommit is the commit the worktree's branch was created at. It is
	// used to detect commits added during the session (see [Status]).
	BaseCommit string
}

Worktree describes a git worktree created for an agent session.

func Create

func Create(ctx context.Context, dir, name string) (*Worktree, error)

Create creates a new git worktree for the repository containing dir and returns it. The worktree lives under the data directory and checks out a freshly created branch so the agent's changes stay isolated from the user's checkout.

When name is empty, a friendly random name (e.g. "focused_turing") is generated. The branch is named "worktree-<name>" and the worktree is stored under <dataDir>/worktrees/<name>.

Returns ErrNotGitRepository when dir is not inside a git worktree, and ErrInvalidName when an explicit name is not a safe path/branch component.

func CreatePR

func CreatePR(ctx context.Context, dir, ref string) (*Worktree, error)

CreatePR creates a git worktree that checks out an existing GitHub pull request so the agent can continue it. ref is a PR number ("123") or a GitHub pull request URL. The PR's head branch is checked out tracking its remote, so commits made in the worktree push back to the pull request.

It delegates PR resolution to the GitHub CLI (gh), which handles head-branch lookup, fork remotes, and upstream tracking. Returns ErrGHNotFound when gh is not installed, ErrInvalidPRRef when ref is malformed, and ErrNotGitRepository when dir is not inside a git repository.

func (*Worktree) Remove

func (wt *Worktree) Remove(ctx context.Context) error

Remove deletes the worktree's directory and its branch, discarding any uncommitted changes, untracked files, and commits. Callers decide when removal is appropriate (e.g. only for worktrees they created, never pre-existing ones).

func (*Worktree) Status

func (wt *Worktree) Status(ctx context.Context) (Status, error)

Status inspects the worktree and reports whether it holds uncommitted changes, untracked files, or commits added since creation.