worktree

package
v0.2.12 Latest Latest
Warning

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

Go to latest
Published: Jul 10, 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

This section is empty.

Functions

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 (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