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 ¶
- Variables
- func Reset(ctx context.Context, root string, baseline Snapshot) error
- func WriteScope(path string, scope Scope) error
- type Scope
- type Snapshot
- func (s Snapshot) Branch() string
- func (s Snapshot) Digest() string
- func (s Snapshot) Document() SnapshotDocument
- func (s Snapshot) Entries() []StatusEntry
- func (s Snapshot) Equal(other Snapshot) bool
- func (s Snapshot) GitAvailable() bool
- func (s Snapshot) HasCommits() bool
- func (s Snapshot) Head() string
- func (s Snapshot) IsGitRepo() bool
- func (s Snapshot) IsSupported() bool
- func (s Snapshot) Porcelain() []byte
- func (s Snapshot) UnsupportedReason() UnsupportedReason
- type SnapshotDocument
- type StatusEntry
- type UnsupportedReason
Constants ¶
This section is empty.
Variables ¶
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
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 ¶
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 ¶
BuildScope captures the final workspace state and compares it to baseline.
func CompareSnapshots ¶
CompareSnapshots derives the task-produced scope from two snapshots.
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot is a deterministic fingerprint of a working tree.
func CaptureExcluding ¶ added in v0.2.15
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) 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) GitAvailable ¶
func (Snapshot) HasCommits ¶
func (Snapshot) IsSupported ¶
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" )