worktree

package
v0.2.15 Latest Latest
Warning

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

Go to latest
Published: Jul 17, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package worktree captures deterministic fingerprints of a workspace's uncommitted state and derives the set of paths produced by a task run.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrResetUnsupported means the baseline snapshot cannot anchor a reset: it
	// was captured outside a git repository, without git available, or before any
	// commit existed.
	ErrResetUnsupported = errors.New("worktree: baseline snapshot cannot anchor a clean reset")
	// ErrResetDirtyBaseline means the baseline carried uncommitted or untracked
	// changes. A snapshot fingerprints that content but does not store it, so the
	// baseline cannot be reconstructed and a hard reset would destroy real work.
	ErrResetDirtyBaseline = errors.New("worktree: baseline snapshot has uncommitted changes")
	// ErrResetRootMismatch means the baseline was captured from a different root
	// than the one the caller asked to reset.
	ErrResetRootMismatch = errors.New("worktree: baseline snapshot was captured from a different root")
	// ErrResetIncomplete means git reported success but the worktree did not come
	// back to the baseline fingerprint.
	ErrResetIncomplete = errors.New("worktree: reset did not restore the baseline state")
)

Functions

func Reset added in v0.2.15

func Reset(ctx context.Context, root string, baseline Snapshot) error

Reset restores root to the exact state recorded by baseline, discarding every commit, staged change, and untracked file produced since the snapshot was taken. Ignored files are left alone.

Only a clean baseline can be restored. Callers should treat any error as "a clean reset is not possible for this worktree" and fall back to whatever their non-destructive path is; the worktree is left untouched when Reset returns before invoking git.

func WriteScope

func WriteScope(path string, scope Scope) error

WriteScope writes a scope artifact as indented JSON.

Types

type Scope

type Scope struct {
	SchemaVersion           string           `json:"schema_version"`
	Supported               bool             `json:"supported"`
	ProducedPaths           []string         `json:"produced_paths"`
	PreExistingPaths        []string         `json:"pre_existing_paths,omitempty"`
	PreExistingChangedPaths []string         `json:"pre_existing_changed_paths,omitempty"`
	UnsupportedReason       string           `json:"unsupported_reason,omitempty"`
	Error                   string           `json:"error,omitempty"`
	Baseline                SnapshotDocument `json:"baseline"`
	Final                   SnapshotDocument `json:"final"`
}

Scope describes which dirty paths were produced by a task relative to a pre-agent baseline snapshot.

func BuildScope

func BuildScope(ctx context.Context, root string, baseline Snapshot) (Scope, error)

BuildScope captures the final workspace state and compares it to baseline.

func CompareSnapshots

func CompareSnapshots(baseline Snapshot, final Snapshot) Scope

CompareSnapshots derives the task-produced scope from two snapshots.

func ReadScope

func ReadScope(path string) (Scope, error)

ReadScope reads a persisted worktree scope artifact.

func (Scope) Unchanged

func (s Scope) Unchanged() bool

Unchanged reports whether no task-produced or contaminated changes are present.

type Snapshot

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

Snapshot is a deterministic fingerprint of a working tree.

func Capture

func Capture(ctx context.Context, root string) (Snapshot, error)

Capture fingerprints the workspace at root using git.

func CaptureExcluding added in v0.2.15

func CaptureExcluding(ctx context.Context, root string, excludedPaths ...string) (Snapshot, error)

CaptureExcluding fingerprints the workspace while omitting paths owned by the runtime rather than the agent. Exclusions are scoped to this snapshot and do not mutate repository ignore configuration.

func (Snapshot) Branch

func (s Snapshot) Branch() string

func (Snapshot) Digest

func (s Snapshot) Digest() string

func (Snapshot) Document

func (s Snapshot) Document() SnapshotDocument

Document returns a JSON-safe representation of the snapshot.

func (Snapshot) Entries

func (s Snapshot) Entries() []StatusEntry

Entries returns parsed porcelain entries with per-path fingerprints.

func (Snapshot) Equal

func (s Snapshot) Equal(other Snapshot) bool

Equal reports whether two snapshots represent the same working-tree state.

func (Snapshot) GitAvailable

func (s Snapshot) GitAvailable() bool

func (Snapshot) HasCommits

func (s Snapshot) HasCommits() bool

func (Snapshot) Head

func (s Snapshot) Head() string

func (Snapshot) IsGitRepo

func (s Snapshot) IsGitRepo() bool

func (Snapshot) IsSupported

func (s Snapshot) IsSupported() bool

func (Snapshot) Porcelain

func (s Snapshot) Porcelain() []byte

Porcelain returns a copy of the raw git porcelain v1 -z status payload.

func (Snapshot) UnsupportedReason

func (s Snapshot) UnsupportedReason() UnsupportedReason

type SnapshotDocument

type SnapshotDocument struct {
	SchemaVersion     string            `json:"schema_version"`
	Supported         bool              `json:"supported"`
	GitAvailable      bool              `json:"git_available"`
	IsGitRepo         bool              `json:"is_git_repo"`
	HasCommits        bool              `json:"has_commits"`
	Head              string            `json:"head,omitempty"`
	Branch            string            `json:"branch,omitempty"`
	Digest            string            `json:"digest,omitempty"`
	UnsupportedReason string            `json:"unsupported_reason,omitempty"`
	RawPorcelainZHex  string            `json:"raw_porcelain_z_hex,omitempty"`
	Entries           []StatusEntry     `json:"entries,omitempty"`
	TrackedSymlinks   map[string]string `json:"tracked_symlinks,omitempty"`
}

SnapshotDocument is the JSON-safe representation used in scope artifacts.

type StatusEntry

type StatusEntry struct {
	Path           string `json:"path"`
	OriginalPath   string `json:"original_path,omitempty"`
	Kind           string `json:"kind"`
	IndexStatus    string `json:"index_status"`
	WorktreeStatus string `json:"worktree_status"`
	Fingerprint    string `json:"fingerprint,omitempty"`
}

StatusEntry is one git porcelain v1 -z status entry captured in a snapshot.

func ParsePorcelain

func ParsePorcelain(raw []byte) ([]StatusEntry, error)

ParsePorcelain parses git status --porcelain=v1 -z output.

type UnsupportedReason

type UnsupportedReason string

UnsupportedReason describes why a working-tree snapshot could not be captured.

const (
	// UnsupportedReasonBlankRoot means the caller did not provide a workspace root.
	UnsupportedReasonBlankRoot UnsupportedReason = "blank_root"
	// UnsupportedReasonNonGit means the workspace root does not contain git metadata.
	UnsupportedReasonNonGit UnsupportedReason = "non_git"
	// UnsupportedReasonGitMissing means the git executable could not be found.
	UnsupportedReasonGitMissing UnsupportedReason = "git_missing"
	// UnsupportedReasonNoCommits means HEAD could not be resolved.
	UnsupportedReasonNoCommits UnsupportedReason = "no_commits"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL