workspace

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package workspace manages Git mirrors and detached worktrees used to inspect candidate contributions.

Paths are contained beneath one managed root, repository hooks and optional helpers are disabled, command output is bounded, and dirty worktrees require explicit force before removal. Creating a workspace invokes git but never executes repository-controlled code.

Index

Constants

View Source 
const (
	// WorkspaceSnapshotVersion identifies the composite candidate identity contract.
	WorkspaceSnapshotVersion = "workspace-snapshot.v1"
)

Variables

View Source 
var (
	ErrExists         = errors.New("workspace already exists")
	ErrNotFound       = errors.New("workspace not found")
	ErrNotManaged     = errors.New("path is not a managed workspace")
	ErrDirty          = errors.New("dirty workspace cannot be removed without force")
	ErrMirrorExists   = errors.New("mirror already exists")
	ErrMirrorInvalid  = errors.New("existing mirror path is not a valid bare repository")
	ErrMirrorNotFound = errors.New("mirror not found")
	ErrInvalidName    = errors.New("invalid name")
	ErrInvalidRemote  = errors.New("invalid remote")
	ErrRemoteMismatch = errors.New("existing mirror remote does not match requested remote")
	ErrPathChanged    = errors.New("workspace path identity changed")
)

Functions

This section is empty.

Types

type AdoptOptions added in v0.10.0 

type AdoptOptions struct {
	Path    string
	BaseRef string
	Name    string
}

AdoptOptions identifies an existing worktree without granting ownership of its files or refs.

type CommitSummary added in v0.10.0 

type CommitSummary struct {
	SHA     string `json:"sha"`
	Subject string `json:"subject"`
}

CommitSummary is one bounded commit header between base and HEAD.

type ContentDigest added in v0.10.0 

type ContentDigest struct {
	SHA256 string `json:"sha256"`
	Bytes  int64  `json:"bytes"`
}

ContentDigest identifies bounded content without embedding it.

type LocalWorktree added in v0.19.0 

type LocalWorktree struct {
	Path    string
	Branch  string
	HeadSHA string
	Remotes map[string][]string
}

LocalWorktree is a read-only inspection of a Git worktree. It deliberately contains no ownership or workflow identity; callers may use it for routing without adopting the path or changing refs.

func InspectPath added in v0.19.0 

func InspectPath(ctx context.Context, path string, runner Runner) (LocalWorktree, error)

InspectPath reads the current branch, HEAD, and configured remotes from a local worktree. It does not fetch, write refs, invoke hooks, or modify the worktree. A nil runner uses the safe default Git runner.

type Manager 

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

Manager manages Git mirrors and detached worktrees under a single root.

func NewManager 

func NewManager(root string, runner Runner) (*Manager, error)

NewManager creates a manager and its root when necessary. A nil runner uses the default git runner.

func OpenManager added in v0.10.0 

func OpenManager(root string, runner Runner) (*Manager, error)

OpenManager opens an existing manager root without creating filesystem state. Use it for read-only workspace inspection paths.

func (*Manager) Adopt added in v0.10.0 

func (m *Manager) Adopt(ctx context.Context, opts AdoptOptions) (*Workspace, error)

Adopt inspects an existing worktree without fetching, changing refs, or taking ownership of the path. The returned administrative identities are revalidated by later workspace operations.

func (*Manager) ChangedFilesByPath 

func (m *Manager) ChangedFilesByPath(ctx context.Context, path, baseSHA string) ([]string, error)

ChangedFilesByPath returns raw Git paths changed from the supplied base. Git owns rename, deletion, and quoted-path handling; NUL delimiters preserve paths containing whitespace or other special characters.

func (*Manager) ChangedFilesWorkspace added in v0.10.0 

func (m *Manager) ChangedFilesWorkspace(ctx context.Context, ws *Workspace) ([]string, error)

ChangedFilesWorkspace revalidates workspace authority before listing files.

func (*Manager) CheckMerge added in v0.5.0 

func (m *Manager) CheckMerge(ctx context.Context, path, baseOID, headOID string) (MergeCheck, error)

CheckMerge compares already-fetched revisions without fetching or changing refs, the index, or a worktree.

func (*Manager) CheckMergeWorkspace added in v0.10.0 

func (m *Manager) CheckMergeWorkspace(ctx context.Context, ws *Workspace, baseOID, headOID string) (MergeCheck, error)

CheckMergeWorkspace revalidates workspace authority before comparing refs.

func (*Manager) Clone 

func (m *Manager) Clone(ctx context.Context, remote, name string) error

Clone clones remote into a bare mirror under the managed root.

func (*Manager) Create 

func (m *Manager) Create(ctx context.Context, mirrorName, baseRef, candidateRef, name string) (*Workspace, error)

Create creates a detached worktree from mirrorName at candidateRef against baseRef.

func (*Manager) Diff 

func (m *Manager) Diff(ctx context.Context, name string) (string, error)

Diff returns the current worktree diff against its recorded base SHA, including staged and unstaged changes without invoking external diff tools.

func (*Manager) DiffByPath 

func (m *Manager) DiffByPath(ctx context.Context, path, baseSHA string) (string, error)

DiffByPath returns the diff for a workspace path against the supplied base SHA, including staged and unstaged changes.

func (*Manager) DiffWorkspace added in v0.10.0 

func (m *Manager) DiffWorkspace(ctx context.Context, ws *Workspace) (string, error)

DiffWorkspace revalidates workspace authority before reading its diff.

func (*Manager) Fetch 

func (m *Manager) Fetch(ctx context.Context, name string) error

Fetch updates an existing mirror.

func (*Manager) Get 

func (m *Manager) Get(name string) (*Workspace, bool)

Get returns a workspace by name.

func (*Manager) HasUntrackedByPath 

func (m *Manager) HasUntrackedByPath(ctx context.Context, path string) (bool, error)

HasUntrackedByPath reports whether a managed workspace contains untracked, non-ignored files. Callers preparing a complete diff must handle these explicitly because git diff does not include them.

func (*Manager) HasUntrackedWorkspace added in v0.10.0 

func (m *Manager) HasUntrackedWorkspace(ctx context.Context, ws *Workspace) (bool, error)

HasUntrackedWorkspace revalidates workspace authority before reading files.

func (*Manager) List 

func (m *Manager) List() []*Workspace

List returns all workspaces sorted by name.

func (*Manager) MergeBase 

func (m *Manager) MergeBase(ctx context.Context, name string) (string, error)

MergeBase recomputes the merge base for the workspace base and candidate.

func (*Manager) Remove 

func (m *Manager) Remove(ctx context.Context, path string, force bool) error

Remove removes the worktree at path. It refuses paths outside the managed root, unrecorded paths, and dirty workspaces unless force is true.

func (*Manager) Resolve 

func (m *Manager) Resolve(ctx context.Context, mirrorName, ref string) (string, error)

Resolve resolves a ref to a full SHA in the named mirror.

func (*Manager) SnapshotByPath added in v0.10.0 

func (m *Manager) SnapshotByPath(ctx context.Context, path, baseSHA, mergeBase string) (Snapshot, error)

SnapshotByPath derives a bounded, no-hook identity for a managed worktree.

func (*Manager) Status 

func (m *Manager) Status(ctx context.Context, name string) (Status, error)

Status reports whether the workspace has uncommitted changes.

func (*Manager) StatusByPath 

func (m *Manager) StatusByPath(ctx context.Context, path string) (Status, error)

StatusByPath reports the dirty state of any workspace path inside the managed root without requiring the workspace to be loaded in memory.

func (*Manager) StatusWorkspace added in v0.10.0 

func (m *Manager) StatusWorkspace(ctx context.Context, ws *Workspace) (Status, error)

StatusWorkspace revalidates workspace authority before reading status.

func (*Manager) UntrackedFilesByPath added in v0.10.0 

func (m *Manager) UntrackedFilesByPath(ctx context.Context, path string) ([]UntrackedFileSnapshot, error)

UntrackedFilesByPath returns a bounded, deterministic snapshot of untracked, non-ignored files. Git performs path discovery and content hashing.

func (*Manager) ValidateWorkspace added in v0.10.0 

func (m *Manager) ValidateWorkspace(ctx context.Context, ws *Workspace) error

ValidateWorkspace revalidates the authority recorded for a persisted workspace before it is used.

func (*Manager) ValidateWorkspacePath added in v0.10.0 

func (m *Manager) ValidateWorkspacePath(path string) error

ValidateWorkspacePath verifies that path exists within the managed worktree subtree without invoking Git or changing filesystem state. Mirrors and other manager state are deliberately excluded from executable capabilities.

type MergeCheck added in v0.5.0 

type MergeCheck struct {
	MergeBase  string
	Conflicted bool
	Summary    string
}

MergeCheck is a non-mutating comparison of two already-fetched revisions.

type Ownership added in v0.10.0 

type Ownership string

Ownership distinguishes worktrees created by GitContribute from external worktrees that it may inspect but never remove. 

const (
	// OwnershipManaged marks a worktree created and removable by GitContribute.
	OwnershipManaged Ownership = "managed"
	// OwnershipExternal marks a worktree that GitContribute may inspect but never remove.
	OwnershipExternal Ownership = "external"
)

type Runner 

type Runner interface {
	Run(ctx context.Context, name string, args ...string) (string, error)
}

Runner executes an external command.

func DefaultRunner 

func DefaultRunner() Runner

DefaultRunner returns a Runner backed by the local git executable.

type Snapshot added in v0.10.0 

type Snapshot struct {
	Version          string              `json:"version"`
	Ownership        string              `json:"ownership"`
	BaseSHA          string              `json:"base_sha,omitempty"`
	HeadSHA          string              `json:"head_sha"`
	MergeBase        string              `json:"merge_base,omitempty"`
	Staged           ContentDigest       `json:"staged"`
	Unstaged         ContentDigest       `json:"unstaged"`
	Untracked        []UntrackedResource `json:"untracked"`
	Submodules       []SubmoduleIdentity `json:"submodules"`
	ChangedFiles     []string            `json:"changed_files"`
	Commits          []CommitSummary     `json:"commits"`
	CommitTotal      int                 `json:"commit_total"`
	CommitsTruncated bool                `json:"commits_truncated"`
	Complete         bool                `json:"complete"`
	Gaps             []SnapshotGap       `json:"gaps"`
	SHA256           string              `json:"sha256"`
}

Snapshot is a deterministic composite identity for a managed worktree.

type SnapshotGap added in v0.10.0 

type SnapshotGap struct {
	Code   string `json:"code"`
	Path   string `json:"path,omitempty"`
	Reason string `json:"reason"`
}

SnapshotGap explicitly records candidate content that could not be bound.

type Status 

type Status struct {
	Dirty bool
}

Status reports the dirty state of a workspace.

type SubmoduleIdentity added in v0.10.0 

type SubmoduleIdentity struct {
	Path     string `json:"path"`
	IndexSHA string `json:"index_sha"`
	HeadSHA  string `json:"head_sha,omitempty"`
	Dirty    *bool  `json:"dirty,omitempty"`
}

SubmoduleIdentity binds the index and checked-out identities of a submodule.

type UntrackedFileSnapshot added in v0.10.0 

type UntrackedFileSnapshot struct {
	Path     string
	ObjectID string
}

UntrackedFileSnapshot identifies exact untracked content without returning file bytes. ObjectID is Git's content hash from hash-object --no-filters.

type UntrackedResource added in v0.10.0 

type UntrackedResource struct {
	Path   string `json:"path"`
	Kind   string `json:"kind"`
	Mode   uint32 `json:"mode"`
	SHA256 string `json:"sha256,omitempty"`
	Bytes  int64  `json:"bytes,omitempty"`
}

UntrackedResource identifies one untracked path and its content when bounded.

type Workspace 

type Workspace struct {
	Name            string
	InvestigationID string
	RepoOwner       string
	RepoName        string
	Path            string
	Remote          string
	BaseSHA         string
	CandidateSHA    string
	MergeBase       string
	Dirty           bool
	HasUntracked    bool
	Ownership       Ownership
	GitDir          string
	GitCommonDir    string
	CreatedAt       time.Time
	// contains filtered or unexported fields
}

Workspace is a product-owned record for a Git worktree.

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.