ops

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: GPL-3.0 Imports: 21 Imported by: 0

Documentation

Overview

Package ops is dstow's application core (A13): the verbs as deep modules composing config, repo, engine, ledger, and hooks into structured results. This file carries the composed environment and the shared result vocabulary; the deploy verbs live in deploy.go and adopt in adopt.go.

ops returns data, never output (A4): every diagnostic is a value — cli renders them through the printer. The one exception to "no side channels" is hook execution, whose streams are the caller-injected hooks.Runner; ops itself never touches a process stream.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AdoptMove 

type AdoptMove struct {
	File   string // absolute path in the target world
	Source string // package-relative destination
}

AdoptMove is one adoption: the live file and the package-relative source that received it (a link at File takes its place).

type AdoptRequest 

type AdoptRequest struct {
	File     string // path operand: the real file to adopt
	Package  string // name expression; must resolve to one package
	Occupied bool   // --occupied: every occupied path of the package
	Force    bool   // overwrite differing package content without asking
	DryRun   bool
}

AdoptRequest parameterizes the adopt leaf (§2.4, REQUIREMENTS §8.5): import a real file into a package, a link takes its place, live content always wins. Exactly one of File or Occupied selects the scope.

type AdoptResult 

type AdoptResult struct {
	FQN      name.FQN
	Moves    []AdoptMove // executed — or planned, under dry-run
	Skipped  []AdoptSkip
	Errs     []error // move failures and post-hook failures; completed work stays
	Notes    []string
	Warnings []Warning
	Pruned   []ledger.Pruned
	DryRun   bool
}

AdoptResult is the adopt run as data.

func (*AdoptResult) Failed 

func (r *AdoptResult) Failed() bool

Failed reports whether the run exits nonzero.

type AdoptSkip 

type AdoptSkip struct {
	File   string
	Reason string
}

AdoptSkip is one path adopt left alone, with its reason (a declined confirmation, a non-file occupant).

type AmbiguousNameError 

type AmbiguousNameError struct {
	Input   string
	Matches []name.FQN
}

AmbiguousNameError reports an operand matching more than one entity (§1.2). ops always returns it as data: the interactive explicit-choice treatment is cli's — it renders the sorted qualified spellings as a selection and re-invokes with the chosen one — and non-interactively the error renders as the §1.2 hard refusal naming those spellings.

func (*AmbiguousNameError) Error 

func (e *AmbiguousNameError) Error() string

type App 

type App struct {
	Global     *config.GlobalLevel // loaded global level; nil when absent
	Repos      []repo.Repo         // the built repo set (unordered)
	LedgerPath string              // production: ledger.Path()
	GlobalDir  string              // global config dir; hooks' GlobalScope.Dir
	Hooks      hooks.Runner        // injected hook streams (H6)
	Prompt     Prompter            // confirmation seam; cli owns O12 rendering
	Now        func() time.Time    // entry RecordedAt clock; nil means time.Now

	// Version is the dstow version string cli populates from ldflags; it is
	// info's global "version" field (§2.4). Empty until cli injects it.
	Version string
	// Git is the version-control seam (A17). status uses AheadBehind to report
	// remote repos' behind/ahead as of the last update, no network; cli injects
	// the exec adapter, tests inject git.Fake. Nil when no remote work is done.
	Git git.Port
}

App is the composed environment a verb runs against. The caller (cli) loads the global pieces once — global config, the registry, DSTOW_PATH — and hands them in; ops loads the per-repo and per-package levels itself, per invocation, at use time.

func (*App) Adopt 

func (a *App) Adopt(req AdoptRequest) (*AdoptResult, error)

Adopt runs the adopt leaf. Refusals — an unresolvable or ambiguous package, a path outside the target, a non-file occupant, an ignored path — return as error before anything mutates; per-move outcomes land in the result.

func (*App) AdoptCandidates 

func (a *App) AdoptCandidates(file string) ([]Candidate, []Warning, error)

AdoptCandidates enumerates the packages that could adopt file, ranked: packages already owning neighboring paths first, canonical-FQN order as the tie-break (ruled 2026-07-17 on #44). A pure config+ledger computation — no tree walking (§8.5).

func (*App) Check 

func (a *App) Check() (*CheckReport, error)

Check classifies every ledgered link against config and disk without taking the lock or writing anything (§6.4). clean recomputes this same classification under its lock, so the two can never disagree.

func (*App) Clean 

func (a *App) Clean(req CleanRequest) (*CleanResult, error)

Clean removes the stale links check reported, recomputing the plan fresh under the ledger lock (§6.4). Contradicted entries are pruned by Update; broken links are removed freely; orphans are confirmed per link (unless Force); unobservable entries are left alone.

func (*App) ColorsTheme 

func (a *App) ColorsTheme(ref string, format ColorFormat) (*ColorsThemeResult, error)

ColorsTheme loads a named theme and serializes it (§2.4 colors, A5). It resolves the ref through ui's single theme loader — a path, a user preset, or a bundled preset — and emits it AS LOADED (its declared slots) in canonical order, packed for env (default) or as a theme file for toml. A missing or unreadable theme is a refusal (error); a malformed slot inside a resolvable theme is a warn-and-skip, carried in Warnings.

func (*App) Deploy 

func (a *App) Deploy(req DeployRequest) (*DeployResult, error)

Deploy runs stow, unstow, or restow (§2.4, A13): per-package independence, nested/LIFO hooks over the acting set, and the ledger transaction of §6.4 — all as data. Run-level refusals (ambiguous operand, fold contradiction, ledger refusals) return as error; every per-package outcome is a PackageResult.

func (*App) Info 

func (a *App) Info(req InfoRequest) (*InfoResult, error)

Info reads one scope's fields from config and metadata, never by inspecting targets (§2.4 — that is status's job). A named operand selects a repo or package scope; no name is the global scope. Under -r the scope's containment subtree is visited in turn. Run-level refusals (ambiguity, not-found) return as error.

func (*App) List 

func (a *App) List(req ListRequest) (*ListResult, error)

List enumerates a scope's configured content (§2.4, REQUIREMENTS §7.1): a pure config+source read — it never inspects target dirs. A named operand selects the scope (a repo lists its packages, a package lists its paths); no name lists the repos, unless --packages widens to every repo's packages. Run-level refusals (ambiguity, not-found) return as error; everything else is data.

func (*App) Rebuild 

func (a *App) Rebuild() (*RebuildResult, error)

Rebuild reconstructs the ledger by scanning configured targets (§6.4). The target set is the union of effective targets over all packages of all registered repos; each scanned root's group is replaced with exactly the owned links found there, and roots whose walk fails are left untouched.

func (*App) RepoAdd 

func (a *App) RepoAdd(req RepoAddRequest) (*RepoAddResult, error)

RepoAdd registers a repo from a source (§2.4, REQUIREMENTS §5.1–5.2). It resolves the source (consulting the Prompter for the §1.2 flow), confirms percent-encoding when a segment needs it, clones a remote into the managed directory or registers a local path in place, appends to the registry (dedup-by-source, re-add is a no-op), and returns the packages and shadowing as data. Adding stows nothing unless --stow, which composes a bulk stow scoped to the new repo.

func (*App) RepoRemove 

func (a *App) RepoRemove(req RepoRemoveRequest) (*RepoRemoveResult, error)

RepoRemove unregisters a repo (§2.4, REQUIREMENTS §5.3). It resolves the operand to one repo, applies the still-stowed guard (both repo kinds) and, for a managed clone, the unsaved-work guard — each prompt-or-refuse, both bypassable by --force. A local-path repo is forgotten (directory untouched); a managed clone is also deleted. The registry is saved last.

func (*App) RepoUpdate 

func (a *App) RepoUpdate(req RepoSyncRequest) (*RepoSyncResult, error)

RepoUpdate runs the fetch phase (§2.4 update, REQUIREMENTS §6.1): git.Fetch per remote repo, touching the network and no working tree. Each repo's outcome — fetched, skipped (no upstream), or errored — is data; the run continues past a per-repo failure.

func (*App) RepoUpgrade 

func (a *App) RepoUpgrade(req RepoSyncRequest) (*RepoSyncResult, error)

RepoUpgrade runs the apply phase (§2.4 upgrade, REQUIREMENTS §6.2): git.FFApply per remote repo, fast-forward only, reporting old→new. Divergence or local work refuses loudly as that repo's Err — no stash, merge, or rebase, and never a re-stow (structural drift shows up in status). A *NotInstalledError surfaces as the repo's outcome, never a panic.

func (*App) SnippetRC 

func (a *App) SnippetRC() SnippetResult

SnippetRC returns the shell-rc bootstrap snippet (§9.1): the vendored snippet.sh, embedded at the repo root (B1 as amended per release-ci D26 — one file, one owner) and emitted verbatim (B2). It reads nothing and cannot fail — the text is compiled in — so it takes no request and returns no error.

func (*App) Status 

func (a *App) Status(req StatusRequest) (*StatusResult, error)

Status inspects reality (§2.4 — the only view that lstats targets): expected-vs-actual against current effective config. Names scope to packages or whole repos (empty is every package); a single Path selects the per-path view. Remote repos in scope also report behind/ahead as of the last update. Ambiguity is a run-level refusal (error); everything else is data.

type Candidate 

type Candidate struct {
	FQN       name.FQN
	Source    string // the package-relative source adoption would write
	Neighbors int
}

Candidate is one package that could adopt a file (REQUIREMENTS §8.5): its effective target covers the path, the mapped source is not ignored, and per-package dot-translation decided the source spelling. Neighbors counts the package's ledgered links already living in the file's directory — the ranking signal.

type CheckReport 

type CheckReport struct {
	Findings []Finding
	Warnings []Warning
}

CheckReport is a check run as data (A4): every classified entry and every diagnostic the classification raised.

type Class 

type Class int

Class is a stale-entry classification (§6.4). The order is the precedence order: an entry is the first class it matches. 

const (
	// ClassUnobservable is the #45 ruling (issue comment 5005576678): an
	// observation the classification needs failed with a non-ENOENT error
	// (the link lstat/readlink, or the destination existence check). It is a
	// read-only row whose evidence is the OS error; clean never acts on it.
	ClassUnobservable Class = iota
	// ClassContradicted is Entry.Contradicted's verdict: disk disagrees with
	// the entry (link gone, non-link, or different link text). clean prunes
	// the entry only, never the disk.
	ClassContradicted
	// ClassBroken is a link that agrees with the ledger but whose recorded
	// destination is gone. clean removes the link and the entry, freely.
	ClassBroken
	// ClassOrphaned is an intact link resolving into a known repo that the
	// current config would not produce. clean removes it behind confirmation.
	ClassOrphaned
)

func (Class) String 

func (c Class) String() string

type CleanFinding 

type CleanFinding struct {
	Finding
	Outcome CleanOutcome
	Err     error // set when Outcome is OutcomeFailed
}

CleanFinding is one finding with what clean did about it.

type CleanOutcome 

type CleanOutcome int

CleanOutcome is what clean did with one finding. 

const (
	// OutcomeRemoved: the link was removed and its entry deleted.
	OutcomeRemoved CleanOutcome = iota
	// OutcomePruned: a contradicted entry Update pruned (disk untouched).
	OutcomePruned
	// OutcomeDeclined: an orphan whose confirmation was declined — kept.
	OutcomeDeclined
	// OutcomeFailed: the removal or the prompt errored; the entry stays and
	// the run continues. Err carries the cause.
	OutcomeFailed
	// OutcomeUntouched: an unobservable finding — clean never acts on it.
	OutcomeUntouched
)

func (CleanOutcome) String 

func (o CleanOutcome) String() string

type CleanRequest 

type CleanRequest struct {
	Force bool // remove orphans without confirmation (REQUIREMENTS §1.6)
}

CleanRequest parameterizes a clean run.

type CleanResult 

type CleanResult struct {
	Findings []CleanFinding
	Pruned   []ledger.Pruned
	Warnings []Warning
}

CleanResult is a clean run as data (A4). Findings carries every classified entry with its outcome (contradicted entries appear as pruned rows, drawn from Pruned); Pruned is Update's raw prune evidence.

func (*CleanResult) Failed 

func (r *CleanResult) Failed() bool

Failed reports whether any finding errored (§3.2, A3 exit 1).

type ColorFormat 

type ColorFormat int

ColorFormat selects how ColorsTheme serializes a theme (§2.4 colors). The zero value is the default env form; a format flag never changes the concept (the --json precedent), so cli spells the flag and hands the choice in. 

const (
	// ColorFormatEnv packs the theme as a DSTOW_COLORS string (default).
	ColorFormatEnv ColorFormat = iota
	// ColorFormatTOML emits the sixteen-slot theme-file TOML.
	ColorFormatTOML
)

type ColorsThemeResult 

type ColorsThemeResult struct {
	Ref      string
	Format   ColorFormat
	Text     string
	Warnings []Warning
}

ColorsThemeResult is the resolved theme as data (A4): the ref asked for, the format chosen, the serialized text, and any warn-and-skip diagnostics the theme load raised (an unknown key, a bad value). cli writes Text.

type DeployRequest 

type DeployRequest struct {
	Verb   engine.Verb
	Names  []string // name expressions; empty = bulk
	Adopt  bool     // --adopt (D15): stow/restow only
	DryRun bool     // -n: plan, change nothing (D8)
}

DeployRequest parameterizes one stow/unstow/restow run (§2.4). Empty Names means bulk — the whole registered set; the interactive "stow everything?" gate and --all are cli's, upstream of ops (D2/D9).

type DeployResult 

type DeployResult struct {
	Packages  []PackageResult
	Warnings  []Warning // run-level warnings (config chain, enumeration, …)
	Notes     []string  // run-level announcements (first-run folding note, …)
	RunErrors []error   // repo/global post-hook failures (§9.1.4: scope failed, work stays)
	Pruned    []ledger.Pruned
	DryRun    bool
}

DeployResult is the whole run as data.

func (*DeployResult) Failed 

func (r *DeployResult) Failed() bool

Failed reports whether the run exits nonzero (§3.2, A3 exit 1): any package failed, was blocked, or was not found — or a post hook marked a wider scope failed.

type Field 

type Field struct {
	Name       string
	Group      FieldGroup
	Status     FieldStatus
	Value      any
	Suggestion string
}

Field is one field's value for one scope (§2.4). Value is nil unless Set; it is a string, a bool, or a []string so cli/json render the native type. Suggestion names the nearest applicable field for an Unknown/Illegal ask.

type FieldGroup 

type FieldGroup int

FieldGroup separates a scope's two field families (§2.4): the inherent facts of the thing as it exists (permanently read-only) and the configured values resolved through the config chain. 

const (
	GroupInherent FieldGroup = iota
	GroupConfigured
)

type FieldStatus 

type FieldStatus int

FieldStatus is one field's per-scope outcome, the datum cli maps to §2.4's exit codes: Set → 0, Unset → 1 (applicable but unset/empty), Unknown → 2 (no such field anywhere), Illegal → 2 (a real field, wrong scope). Under -r, cli silently skips Illegal fields instead (§2.4). 

const (
	FieldSet FieldStatus = iota
	FieldUnset
	FieldUnknown
	FieldIllegal
)

type Finding 

type Finding struct {
	TargetRoot string
	Entry      ledger.Entry
	Class      Class
	Evidence   string
}

Finding is one classified ledger entry (§6.4): the target root it lives under, the entry itself, its class, and complete evidence prose.

type FoldConflictError 

type FoldConflictError struct {
	True  []FoldSource // repos whose effective fold is on
	False []FoldSource // repos whose effective fold is off
}

FoldConflictError refuses a run whose repos' effective fold values contradict (REQUIREMENTS §3.3): folding is a property of a target subtree, so a run mixing folded and unfolded repos cannot be honored. With --no-folding stow's only fold flag, the live case is a repo rc declaring false while the global fold_trees says true. The remedy is the global knob.

func (*FoldConflictError) Error 

func (e *FoldConflictError) Error() string

type FoldSource 

type FoldSource struct {
	Repo name.FQN
	File string
}

FoldSource names one repo's effective fold value and where it came from: a migrated .stowrc (honored per-repo, REQUIREMENTS §3.3) or the global setting every rc-less repo inherits.

type InfoRequest 

type InfoRequest struct {
	Name    string
	Fields  []string
	Recurse bool
}

InfoRequest parameterizes an info run (§2.4). Name is the scope operand — empty is the global scope. Fields selects named fields (-f, repeatable); empty means every field of the scope. Recurse (-r) visits the scope's whole containment subtree, per-scope attributed. --json is cli's rendering choice.

type InfoResult 

type InfoResult struct {
	Scopes   []InfoScope
	Warnings []Warning
}

InfoResult is an info run as data (A4): one scope, or many under -r.

type InfoScope 

type InfoScope struct {
	FQN    name.FQN
	Kind   ScopeKind
	Fields []Field
}

InfoScope is one scope's fields, per-scope attributed (§2.4). FQN is zero for the global scope.

type LinkState 

type LinkState int

LinkState is one expected (or ledgered) link's disk verdict. 

const (
	// LinkStowed: a symlink owned by this package sits at the slot.
	LinkStowed LinkState = iota
	// LinkMissing: nothing exists at the slot.
	LinkMissing
	// LinkOccupied: a real file/dir or a foreign link occupies the slot.
	LinkOccupied
	// LinkDamaged: the ledger recorded a link here and disk contradicts it.
	LinkDamaged
)

func (LinkState) String 

func (s LinkState) String() string

type LinkStatus 

type LinkStatus struct {
	Link   string // target-relative
	Source string // package-relative source the current config expects, "" for a ledger-only link
	State  LinkState
	Detail string // evidence prose
}

LinkStatus is one link's per-slot detail (REQUIREMENTS §7.2.4).

type ListKind 

type ListKind int

ListKind names which content a ListResult carries (§2.4: global ⊃ repos ⊃ packages ⊃ paths). 

const (
	// KindRepos lists the global scope's repos (bare list, or --repos).
	KindRepos ListKind = iota
	// KindPackages lists packages — one repo's, or all repos' under --packages.
	KindPackages
	// KindPaths lists a package's raw file paths.
	KindPaths
)

type ListRequest 

type ListRequest struct {
	Name         string
	ReposOnly    bool
	PackagesOnly bool
}

ListRequest parameterizes a list run (§2.4): the read surface over a scope's content. Name is the scope operand — empty is the global scope (the repos). ReposOnly (--repos) and PackagesOnly (--packages) are the flag filters; cli owns their mutual exclusion and any name/flag combination rules. --json is a cli rendering choice over this same data.

type ListResult 

type ListResult struct {
	Kind     ListKind
	Scope    name.FQN
	Repos    []RepoListing
	Packages []PackageListing
	Paths    []PathListing
	Warnings []Warning
}

ListResult is a list run as data (A4). Exactly one of Repos/Packages/Paths is populated per Kind; Scope names the resolved repo or package (zero for the global scope).

type NotFoundError 

type NotFoundError struct {
	Input string
}

NotFoundError reports a view operand that resolved to no entity in the set (§1.4). ops returns it as data; cli renders the §1.4 refusal.

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

type PackageListing 

type PackageListing struct {
	FQN     name.FQN
	Display string
	Repo    name.FQN
}

PackageListing is one package row, always repo-attributed (REQUIREMENTS §7.1). Display is the O9 shortest-unique spelling among the listed set — bare where unambiguous, qualified where a bare name is shared.

type PackageResult 

type PackageResult struct {
	Operand  string   // the operand this result stands for, when no FQN resolved
	FQN      name.FQN // zero when the operand never resolved
	Status   PackageStatus
	Actions  []engine.Action // executed — or planned, under dry-run
	Err      error           // typed: *engine.ConflictError, *hooks.HookError, config errors…
	Notes    []string        // announcements (§1.3): created target, …
	Warnings []Warning
}

PackageResult is one package's line in the run (O8 renders it).

type PackageState 

type PackageState int

PackageState is a package's live deployment state (REQUIREMENTS §7.2), expected-vs-actual against the CURRENT effective config. String returns the CONTEXT.md state strings verbatim (O10: including the space in "partially stowed"). 

const (
	// StateNotStowed: none of the package's expected links are deployed and
	// nothing occupies their slots (also the empty-package case).
	StateNotStowed PackageState = iota
	// StateStowed: every expected link is present and owned by this package.
	StateStowed
	// StatePartiallyStowed: some but not all expected links are deployed.
	StatePartiallyStowed
	// StateOccupied: a real file or a foreign link sits where an expected link
	// would go — neutral, no claim how. Outranks the stowed/partial spectrum:
	// the slot is taken, not "merely missing" (CONTEXT.md package states), so it
	// holds even when some of the package's other links are stowed.
	StateOccupied
	// StateDamaged: dstow's ledger records a link here that disk now
	// contradicts — claimed only with ledger evidence (REQUIREMENTS §7.2).
	StateDamaged
)

func (PackageState) String 

func (s PackageState) String() string

type PackageStatus 

type PackageStatus int

PackageStatus is one package's outcome in a deploy run (§3.2). 

const (
	// StatusSucceeded includes the no-op: a package whose plan was empty
	// succeeded with zero actions (§9.1.5 keeps its hooks quiet too).
	StatusSucceeded PackageStatus = iota
	StatusFailed
	// StatusBlocked marks a package a failed repo- or global-pre hook
	// blocked (§9.1.4); its Err carries the blocking HookError.
	StatusBlocked
	// StatusNotFound marks an operand that resolved to nothing (§3.2:
	// "per-package status line (not-found included)").
	StatusNotFound
)

func (PackageStatus) String 

func (s PackageStatus) String() string

type PackageStatusResult 

type PackageStatusResult struct {
	FQN      name.FQN
	State    PackageState
	Drifted  bool // §7.2 marker: a stowed package whose deployed shape differs from current config
	Links    []LinkStatus
	Warnings []Warning
}

PackageStatusResult is one package's live status (REQUIREMENTS §7.2).

type PathListing 

type PathListing struct {
	Path string
}

PathListing is one raw package path, relative to the package directory (§2.4; ruled: no dot-translation, no ignore application — a plain walk).

type PathStatus 

type PathStatus struct {
	Path       string
	Exists     bool
	IsSymlink  bool
	LinkDest   string
	Kind       string
	Owner      name.FQN
	OwnerKnown bool
	Candidates []Candidate
	Warnings   []Warning
}

PathStatus is the per-path view (REQUIREMENTS §7.2.4): what occupies a path, who owns it per the ledger, and — if occupied — the ranked adoption candidates. Path is the absolute path inspected.

type Prompter 

type Prompter interface {
	// Confirm asks a yes/no question. defaultYes selects the O12 polarity:
	// destructive/bulk questions default No, benign-continue questions
	// default Yes.
	Confirm(question string, defaultYes bool) (bool, error)
}

Prompter answers confirmation prompts of stated intent (D2). ops asks in complete prose; the implementation owns rendering, polarity display, and the non-interactive stance — a non-interactive implementation returns an error naming the unambiguous form rather than answering (§1.2).

type RebuildResult 

type RebuildResult struct {
	Counts   map[string]int // scanned target root → entries recorded
	Warnings []Warning
}

RebuildResult is a rebuild run as data (A4): the per-root entry counts of the roots it scanned, and every diagnostic the scan raised.

type RenameRequestedError 

type RenameRequestedError struct {
	Source string // the canonical encoded source
}

RenameRequestedError reports that the encoding continue-or-rename prompt was answered rename (§1.2 + §2.4 add): the add is cancelled so the user can rename first. It names the encoded form that would otherwise be used.

func (*RenameRequestedError) Error 

func (e *RenameRequestedError) Error() string

type RepoAddRequest 

type RepoAddRequest struct {
	Source string // raw user input (path, URL, qualified, or bare)
	Stow   bool   // --stow: after registering, stow this repo's packages
}

RepoAddRequest parameterizes repo add (§2.4, REQUIREMENTS §5): the raw source operand and the opt-in add-and-stow flag. Classification and the §1.2 confirm/ambiguity flow happen inside — cli hands the raw string in.

type RepoAddResult 

type RepoAddResult struct {
	Source         repo.Source
	FQN            name.FQN
	Managed        bool          // a managed clone (remote source)
	Cloned         bool          // a clone was performed this run
	AlreadyPresent bool          // re-add no-op: the source was already registered
	Packages       []string      // the new repo's enumerated packages
	Shadowed       []string      // bare package names that now need qualification
	Deploy         *DeployResult // populated under --stow
	Notes          []string
	Warnings       []Warning
}

RepoAddResult is the add as data (A4). It names the resolved source and repo FQN, whether a clone happened, the enumerated packages, the bare names that now need qualification (the shadowing announcement, §5.2.4), and — under --stow — the composed deploy run. AlreadyPresent marks the safe, announced re-add no-op (§5.2.3).

type RepoListing 

type RepoListing struct {
	FQN          name.FQN
	Display      string // shortest-unique spelling among the listed repos (O9)
	Source       string // canonical scheme:coordinate — where it came from
	Scheme       string
	Root         string
	ExcludedBulk bool
	Managed      bool
	Session      bool
}

RepoListing is one repo row of a repos listing (§2.4: source, scheme, bulk-exclusion). Source is the canonical FQN spelling of where it came from; Root is its on-disk location; the flags carry no priority (§2.3).

type RepoRemoveRequest 

type RepoRemoveRequest struct {
	Repo   string // name expression resolving to one repo
	Unstow bool   // --unstow: unstow the repo's packages first, no prompt
	Force  bool   // --force: override both guards
}

RepoRemoveRequest parameterizes repo remove (§2.4, REQUIREMENTS §5.3): the repo operand and the two guard bypasses. --unstow unstows first without prompting; --force overrides both guards (unsaved work will be lost).

type RepoRemoveResult 

type RepoRemoveResult struct {
	FQN      name.FQN
	Managed  bool
	Deleted  bool          // the managed clone directory was deleted
	Unstowed *DeployResult // populated when packages were unstowed first
	Notes    []string
	Warnings []Warning
}

RepoRemoveResult is the removal as data. Deleted marks a managed clone whose directory was removed; a local-path repo is only forgotten (its directory is never touched). Unstowed carries the composed unstow run when one happened.

type RepoSync 

type RepoSync struct {
	FQN    name.FQN
	Ahead  int
	Behind int
	Known  bool
	Err    error
}

RepoSync is a remote repo's sync state as of the last update (REQUIREMENTS §7.2.1): behind/ahead from git.Port.AheadBehind, no network. Known is false when the count could not be determined (no git port, or an error), with Err carrying the cause.

type RepoSyncReport 

type RepoSyncReport struct {
	FQN     name.FQN
	Fetched bool
	Old     string
	New     string
	Changed bool
	Skipped bool
	Note    string
	Err     error
}

RepoSyncReport is one repo's outcome in a sync run (A4). For update, Fetched marks a completed fetch. For upgrade, Old/New report the fast-forward and Changed whether it moved. Err carries a per-repo refusal (a *git.DivergedError, local work, or *git.NotInstalledError) — the run continues past it. Skipped marks a named repo with no upstream, with Note saying why.

type RepoSyncRequest 

type RepoSyncRequest struct {
	Names []string // empty = all remote repos
}

RepoSyncRequest parameterizes update and upgrade (§2.4, REQUIREMENTS §6): named repos, or every remote (managed) repo when none are named. Local and session repos have no upstream and are skipped.

type RepoSyncResult 

type RepoSyncResult struct {
	Repos    []RepoSyncReport
	Warnings []Warning
}

RepoSyncResult is the whole sync run as data.

func (*RepoSyncResult) Failed 

func (r *RepoSyncResult) Failed() bool

Failed reports whether any repo's outcome was an error (exit nonzero).

type ScopeKind 

type ScopeKind int

ScopeKind names an info scope (§2.4: global installation, a repo, a package). 

const (
	ScopeGlobal ScopeKind = iota
	ScopeRepo
	ScopePackage
)

type SnippetResult 

type SnippetResult struct {
	// Text is the exact bytes to emit, verbatim and unmodified.
	Text string
}

SnippetResult is one canned snippet as data (§2.4 snippet). ops returns the text; cli writes it to stdout — ops never touches a stream (A4).

type SourceAmbiguousError 

type SourceAmbiguousError struct {
	Input  string
	Github repo.Source
	Local  repo.Source
}

SourceAmbiguousError reports a bare owner/name that could mean either the github source or an existing local directory (§1.2 + §5.2.2): the §1.2 explicit-choice case. ops returns it as data — cli renders the choice and re-invokes with one of the two qualified spellings — and non-interactively it renders as the hard refusal naming both.

func (*SourceAmbiguousError) Error 

func (e *SourceAmbiguousError) Error() string

type SourceDeclinedError 

type SourceDeclinedError struct {
	Input          string
	Interpretation string
}

SourceDeclinedError reports that the interactive github interpretation of a bare source was declined (§1.2). Its message names the qualified spelling to use instead.

func (*SourceDeclinedError) Error 

func (e *SourceDeclinedError) Error() string

type SourceUnresolvableError 

type SourceUnresolvableError struct {
	Input string
}

SourceUnresolvableError reports a bare input that is neither an owner/name github source nor an existing local directory (§1.4). Every refusal names its remedy.

func (*SourceUnresolvableError) Error 

func (e *SourceUnresolvableError) Error() string

type StatusRequest 

type StatusRequest struct {
	Names []string
	Path  string
}

StatusRequest parameterizes a status run (§2.4). Names scope to packages or whole repos; empty Names is every package. Path selects the per-path view (mutually exclusive with Names; cli routes a path operand here per §1.3). --json is cli's rendering choice.

type StatusResult 

type StatusResult struct {
	Packages []PackageStatusResult
	Repos    []RepoSync
	Path     *PathStatus
	Warnings []Warning
}

StatusResult is a status run as data (A4). For the names/bulk view Packages and Repos are populated; for the per-path view Path is set.

type StillStowedError 

type StillStowedError struct {
	FQN name.FQN
}

StillStowedError refuses a removal that would orphan or dangle stowed links (REQUIREMENTS §5.3): the repo still has ledgered links. The remedy names the two bypasses. Applies to local and managed repos alike.

func (*StillStowedError) Error 

func (e *StillStowedError) Error() string

type UnsavedWorkError 

type UnsavedWorkError struct {
	FQN   name.FQN
	Dir   string
	Prose string // git's account of what would be lost
}

UnsavedWorkError refuses deleting a managed clone that holds work not present at its source (REQUIREMENTS §5.3): the prose names what would be lost. Only managed clones hit this — a local path is never deleted.

func (*UnsavedWorkError) Error 

func (e *UnsavedWorkError) Error() string

type Warning 

type Warning struct {
	Source string
	Detail string
	Fix    string
}

Warning is one diagnostic as data (A4), the same shape config and repo speak: Source is where it arose, Detail is complete prose, Fix an optional remedy.

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.