gitrunner

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrDiffSnapshotTooLarge        = errors.New("git diff exceeds the safe snapshot limit")
	ErrReviewSnapshotTooLarge      = errors.New("git workspace review exceeds the safe snapshot limit")
	ErrReviewSnapshotChanged       = errors.New("git workspace changed while its review snapshot was captured")
	ErrReviewSnapshotInvalid       = errors.New("git workspace review snapshot is invalid")
	ErrDiffSnapshotApplied         = errors.New("git diff snapshot was applied but cleanup did not complete")
	ErrDiffSnapshotCleanupFailed   = errors.New("git diff snapshot cleanup did not complete")
	ErrDiffSnapshotOutcomeUnknown  = errors.New("git diff snapshot mutation outcome is unknown")
	ErrIndexVisibilityUnsupported  = errors.New("git index visibility flags are unsupported by workspace review and discard")
	ErrSubmoduleChangesUnsupported = errors.New("git submodule changes are unsupported by workspace discard")
	ErrTrackedPathTopologyUnsafe   = errors.New("tracked workspace path topology is unsafe for discard")
	ErrStagedChangesUnsupported    = errors.New("staged git changes are not supported by workspace discard")
	ErrStatusSnapshotTooLarge      = errors.New("git status exceeds the safe snapshot limit")
	ErrDiffSnapshotInvalid         = errors.New("git diff snapshot is invalid")
	ErrDiffSnapshotNotApplicable   = errors.New("git diff snapshot no longer applies cleanly")
)

Functions

func DiffRevision 

func DiffRevision(rawDiff string) string

DiffRevision returns the legacy patch-only display digest. It is not a mutation precondition; discard authority additionally binds workspace-root identity through diffDiscardRevision. The empty patch has one deterministic display revision.

func RejectEffectiveContentConversionFilters 

func RejectEffectiveContentConversionFilters(ctx context.Context, output string) error

RejectEffectiveContentConversionFilters validates the NUL-delimited triples emitted by `git check-attr -z --all` and rejects any effective filter.

func SanitizedEnv 

func SanitizedEnv(env []string) []string

Types

type DiffSnapshot 

type DiffSnapshot struct {
	Stat            string
	Diff            string
	Revision        string
	DiscardRevision string
	Paths           []string
	// contains filtered or unexported fields
}

DiffSnapshot contains a bounded, exact raw Git patch, its byte-exact sorted path set, and its digests. Diff is intentionally not trimmed: callers that need a display projection may trim their copy, while mutation callers retain the byte-exact patch covered by DiscardRevision. Paths is derived from Diff by Git's own NUL-delimited patch parser; it is not independently authoritative. Revision is display-only legacy evidence. DiscardRevision additionally binds the patch to the reviewed workspace-root identity and is the only token that callers may use as a mutation precondition; truncated patches fail closed.

type IndexVisibilityEntry added in v0.7.0 

type IndexVisibilityEntry struct {
	Path string
	Kind string
}

IndexVisibilityEntry identifies a tracked path whose index flags can hide a worktree edit from ordinary status and diff output.

type LocalRunner 

type LocalRunner struct {
	Process       processrunner.Runner
	Env           []string
	ReadOnlyPaths []string
	// contains filtered or unexported fields
}

func NewLocalRunner 

func NewLocalRunner() *LocalRunner

func (*LocalRunner) Clone 

func (r *LocalRunner) Clone(ctx context.Context, sourcePath, workspacePath string) (Result, error)

func (*LocalRunner) CurrentRef 

func (r *LocalRunner) CurrentRef(ctx context.Context, workspace string) string

func (*LocalRunner) Diff 

func (r *LocalRunner) Diff(ctx context.Context, workspace string, maxBytes int64) (string, string)

func (*LocalRunner) IsWorkTree 

func (r *LocalRunner) IsWorkTree(ctx context.Context, workspace string) bool

func (*LocalRunner) NewReadOnlyView 

func (r *LocalRunner) NewReadOnlyView(ctx context.Context, workspace string) (*ReadOnlyView, error)

NewReadOnlyView snapshots the non-executable repository metadata needed by status/diff and returns a runner that never loads the source repository's mutable config. The caller must Close the view.

func (*LocalRunner) ReverseApplySnapshot 

func (r *LocalRunner) ReverseApplySnapshot(ctx context.Context, workspace string, snapshot DiffSnapshot, paths []string) (result Result, returnErr error)

ReverseApplySnapshot conditionally removes selected changes from the exact patch and workspace root covered by snapshot.DiscardRevision. Git applies the reverse hunks directly to the current worktree: overlapping edits made after the snapshot cause the whole operation to fail, while unrelated and non-overlapping edits survive.

func (*LocalRunner) ReviewAndDiffMatchWorkspace added in v0.7.0 

func (r *LocalRunner) ReviewAndDiffMatchWorkspace(workspace string, review ReviewSnapshot, diff DiffSnapshot) bool

ReviewAndDiffMatchWorkspace proves that independently captured review and discard snapshots came from the directory currently reachable at workspace. The filesystem identity remains internal rather than becoming HTTP state.

func (*LocalRunner) ReviewMatchesWorkspace added in v0.7.0 

func (r *LocalRunner) ReviewMatchesWorkspace(workspace string, review ReviewSnapshot) bool

ReviewMatchesWorkspace binds a separately pinned preview reader to the same directory that produced the Git review evidence.

func (*LocalRunner) Run 

func (r *LocalRunner) Run(ctx context.Context, workspace string, args ...string) (Result, error)

func (*LocalRunner) RunLimited 

func (r *LocalRunner) RunLimited(ctx context.Context, workspace string, maxBytes int64, args ...string) (Result, error)

func (*LocalRunner) RunLimitedReadOnly 

func (r *LocalRunner) RunLimitedReadOnly(ctx context.Context, workspace string, maxBytes int64, args ...string) (Result, error)

RunLimitedReadOnly executes a fixed Git invocation with OS-level network isolation and, under bwrap, a read-only host filesystem. Callers must still disable Git features such as fsmonitor and optional index locks because the wrapper is best-effort on platforms where no kernel sandbox is available.

func (*LocalRunner) RunLimitedReadOnlyInput 

func (r *LocalRunner) RunLimitedReadOnlyInput(ctx context.Context, workspace string, maxBytes int64, stdin string, args ...string) (Result, error)

RunLimitedReadOnlyInput is RunLimitedReadOnly with caller-provided standard input. Callers must cap that input; this avoids platform command-line limits for fixed Git commands such as check-attr.

func (*LocalRunner) SnapshotDiff 

func (r *LocalRunner) SnapshotDiff(ctx context.Context, workspace string, maxBytes int64) (DiffSnapshot, error)

SnapshotDiff captures the complete scoped tracked working-tree patch up to maxBytes and returns a content revision over Git's raw stdout, including its final newline. Scoped staged changes fail closed until index-aware discard is supported. A truncated display must never become mutation authority because edits beyond the retained prefix would otherwise share a revision.

func (*LocalRunner) SnapshotReview added in v0.7.0 

func (r *LocalRunner) SnapshotReview(ctx context.Context, workspace string, maxBytes int64) (ReviewSnapshot, error)

SnapshotReview captures all three Git workspace-review layers without granting mutation authority to any of them. Each tracked patch and the NUL-delimited status inventory must fit maxBytes. The path sets derived from the exact patches must agree with the final status observation; otherwise a concurrent workspace transition fails this read rather than rendering a falsely complete review.

func (*LocalRunner) SnapshotReviewFile added in v0.7.0 

func (r *LocalRunner) SnapshotReviewFile(ctx context.Context, workspace, path string, maxBytes int64) (ReviewLayerSnapshot, ReviewStatusEntry, bool, error)

SnapshotReviewFile captures one tracked working-tree entry without charging unrelated files against its bounded patch budget. It grants no mutation authority and deliberately ignores the staged layer.

func (*LocalRunner) StatusPorcelain 

func (r *LocalRunner) StatusPorcelain(ctx context.Context, workspace string, maxBytes int64) (string, error)

StatusPorcelain captures a passive, NUL-delimited porcelain-v1 status for exactly Workspace. Returned paths are normalized relative to Workspace even when it is nested inside a larger Git worktree.

func (*LocalRunner) Worktrees 

func (r *LocalRunner) Worktrees(ctx context.Context, workspace string) ([]Worktree, error)

type ReadOnlyView 

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

ReadOnlyView is an immutable Git control-plane snapshot for passive inspection. The worktree, index, and object database remain the source repository's read-only data, but Git reads configuration, HEAD, refs, and info attributes from a private temporary gitdir. Repository config changes therefore cannot introduce executable helpers between validation and use.

func (*ReadOnlyView) Close 

func (v *ReadOnlyView) Close() error

func (*ReadOnlyView) IndexVisibilityEntries added in v0.7.0 

func (v *ReadOnlyView) IndexVisibilityEntries(ctx context.Context) ([]IndexVisibilityEntry, error)

IndexVisibilityEntries returns scoped index flags that can suppress ordinary status and diff output. Callers must not claim a complete review or grant discard authority while any entry is present.

func (*ReadOnlyView) RejectContentConversionAttributes 

func (v *ReadOnlyView) RejectContentConversionAttributes(ctx context.Context) error

RejectContentConversionAttributes fails closed when a tracked path in the scoped workspace has an effective filter attribute. Git's clean/process filters are executable repository configuration, so a passive status or diff must not continue when conversion behavior is effective or ambiguous.

func (*ReadOnlyView) RejectContentConversionAttributesForPath added in v0.7.0 

func (v *ReadOnlyView) RejectContentConversionAttributesForPath(ctx context.Context, path string) error

RejectContentConversionAttributesForPath applies the same passive filter policy without enumerating unrelated tracked paths for a targeted review.

func (*ReadOnlyView) RejectStagedChanges 

func (v *ReadOnlyView) RejectStagedChanges(ctx context.Context) error

RejectStagedChanges ensures a successful SnapshotDiff covers every tracked change in its scoped workspace. Conditional reverse apply currently owns the worktree layer only; accepting an index-only change would report a false clean snapshot, while folding HEAD-relative changes into the worktree patch would leave the index changed. Staged and mixed-layer support therefore remains an explicit follow-up rather than weakening discard semantics here.

func (*ReadOnlyView) RejectSubmoduleChanges added in v0.7.0 

func (v *ReadOnlyView) RejectSubmoduleChanges(ctx context.Context) error

RejectSubmoduleChanges prevents a root-worktree patch from becoming discard authority for Gitlink state. Reverse-applying that patch cannot reliably restore the nested repository's checked-out commit or internal dirtiness.

func (*ReadOnlyView) RunLimited 

func (v *ReadOnlyView) RunLimited(ctx context.Context, maxBytes int64, args ...string) (Result, error)

func (*ReadOnlyView) RunLimitedInput 

func (v *ReadOnlyView) RunLimitedInput(ctx context.Context, maxBytes int64, stdin string, args ...string) (Result, error)

RunLimitedInput runs a fixed passive Git command with caller-provided input.

func (*ReadOnlyView) UnmergedPaths added in v0.7.0 

func (v *ReadOnlyView) UnmergedPaths(ctx context.Context) ([]string, error)

UnmergedPaths reads conflict stages directly from the index. Git porcelain status can depend on repository-state files outside the index; the passive view intentionally snapshots only the minimum immutable metadata, so destructive review must independently fail closed on any unmerged entry.

func (*ReadOnlyView) WorkspacePrefix 

func (v *ReadOnlyView) WorkspacePrefix() string

WorkspacePrefix returns Workspace relative to WorkTree. Git paths emitted with --full-name are relative to this same root.

type Result 

type Result = processrunner.Result

type ReviewLayerSnapshot added in v0.7.0 

type ReviewLayerSnapshot struct {
	Stat             string
	Diff             string
	Paths            []string
	Complete         bool
	Exact            bool
	IncompleteReason string
}

ReviewLayerSnapshot is one bounded tracked-change layer captured for operator review. Complete means its inventory/display projection was captured without truncation; Exact separately records whether its patch is byte-exact (binary metadata can be complete but non-exact). Unlike DiffSnapshot it is read-only evidence and must never be accepted as mutation authority.

type ReviewSnapshot added in v0.7.0 

type ReviewSnapshot struct {
	Staged    ReviewLayerSnapshot
	Unstaged  ReviewLayerSnapshot
	Untracked []ReviewUntrackedEntry
	Hidden    []IndexVisibilityEntry
	Status    []ReviewStatusEntry
	Complete  bool
	// contains filtered or unexported fields
}

ReviewSnapshot describes the staged (HEAD to index), unstaged (index to worktree), and untracked path layers visible in a workspace. It deliberately carries no mutation precondition: only DiffSnapshot can authorize discard.

type ReviewStatusEntry added in v0.7.0 

type ReviewStatusEntry struct {
	Path           string
	IndexStatus    byte
	WorktreeStatus byte
	UntrackedKind  string
	Conflict       bool
}

ReviewStatusEntry retains Git's two-layer porcelain status for one scoped path. Status bytes use Git porcelain-v1 semantics and are never trimmed.

type ReviewUntrackedEntry added in v0.7.0 

type ReviewUntrackedEntry struct {
	Path string
	Kind string
}

type Runner 

type Runner interface {
	Run(ctx context.Context, workspace string, args ...string) (Result, error)
	CurrentRef(ctx context.Context, workspace string) string
	IsWorkTree(ctx context.Context, workspace string) bool
	Worktrees(ctx context.Context, workspace string) ([]Worktree, error)
	Diff(ctx context.Context, workspace string, maxBytes int64) (string, string)
	Clone(ctx context.Context, sourcePath, workspacePath string) (Result, error)
}

type Worktree 

type Worktree struct {
	Path     string
	Head     string
	Branch   string
	Detached bool
	Bare     bool
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.