Documentation
¶
Overview ¶
Package vcs provides a VCS interface and built-in implementations for git, hg (Mercurial), sl (Sapling), and jj (Jujutsu). It also handles autodetection of the active VCS for a workspace and resolution of configuration.
Index ¶
- func Checkpoint(ctx context.Context, dir string, res types.VCSResolution) (types.VCSCheckpoint, error)
- func InstallableVCSes() []string
- func Installer(name string) (types.MergeDriverInstaller, bool)
- func IsSecondaryCheckout(dir string) bool
- func Resolve(_ context.Context, root, runtimeBase string, opts types.VCSOptions) (types.VCSResolution, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Checkpoint ¶ added in v0.4.0
func Checkpoint(ctx context.Context, dir string, res types.VCSResolution) (types.VCSCheckpoint, error)
Checkpoint resolves what is true in dir right now: the head revision, the branch carrying it, whether the tree is dirty, and a digest of the uncommitted patch.
It READS. Nothing here writes a tag, a stash, a ref, or a file, and nothing about the tree is different afterwards - so a caller recording one per lease pays only the cost of the probes, and a checkpoint nobody kept has cost nothing. magus emits the facts; whoever holds the ledger decides what they mean.
One Metadata call covers revision, branch and dirtiness, so a clean tree spawns no second round of processes. The patch is read only when the tree is dirty, which is also the only case where a digest would say anything.
func InstallableVCSes ¶
func InstallableVCSes() []string
InstallableVCSes returns the names of built-in VCS drivers that support merge-driver installation.
func Installer ¶
func Installer(name string) (types.MergeDriverInstaller, bool)
Installer returns the merge-driver installer for the named VCS, or (nil, false).
func IsSecondaryCheckout ¶ added in v0.3.0
IsSecondaryCheckout reports whether dir is a second checkout of a repository under any supported VCS (a git linked worktree, an `hg share`, a jj secondary workspace). Discovery skips such dirs so a repo's projects and spells are not re-indexed and made to shadow the originals (MGS1002). Each backend matches its own on-disk signature, so detection favors no single VCS and needs no resolution step (the active VCS is not yet known when discovery walks the tree).
func Resolve ¶
func Resolve(_ context.Context, root, runtimeBase string, opts types.VCSOptions) (types.VCSResolution, error)
Resolve picks the active VCS for root: disabled → explicit → auto (claim dir) → default (git). Base ref: runtimeBase → opts.BaseRef → MAGUS_VCS_BASE_REF → per-VCS env → built-in default.
Example ¶
ExampleResolve shows how Resolve picks the active VCS and base ref for a workspace root. Resolve is typically called once per magus invocation and its result is cached in the Workspace.
With no VCS markers on disk and no overrides, Resolve does not error: it falls back to the built-in default driver (git) with source "default" and git's default base ref. The MAGUS_VCS_* environment variables are cleared first so the output does not depend on the caller's environment.
for _, k := range []string{
"MAGUS_VCS_ENABLED",
"MAGUS_VCS_NAME",
"MAGUS_VCS_BASE_REF",
"MAGUS_VCS_GIT_BASE_REF",
} {
_ = os.Unsetenv(k)
}
// A path with no .git/.hg/.jj marker, so auto-detection finds nothing and
// Resolve uses the default driver.
root := "/nonexistent/path"
res, err := Resolve(context.Background(), root, "", types.VCSOptions{})
if err != nil {
fmt.Println("error:", err)
return
}
fmt.Println("source:", res.Source)
fmt.Println("vcs:", res.Name)
fmt.Println("base:", res.Base)
Output: source: default vcs: git base: origin/main
Types ¶
This section is empty.
Source Files