magus v0.4.3 is out. See what's new
¶ View generated markdown
4 min read

magus-vcs

Staging and conflict resolution that knows what is generated

Synopsis

magus vcs <add|resolve|checkpoint|merge-driver> [flags]

Description

Version-control operations that read the workspace's output declarations, so generated files and hand-written sources are treated differently.

add stages what the workspace declares: sources, and the generated outputs a source change in the same commit accounts for. Anything undeclared is reported rather than swept in, which is the difference between it and git add -A.

--untracked says yes to every undeclared path at once, so it needs --reason: it drops the one report that separates this command from git add -A, and the files it sweeps in land in a commit everybody pulls. The reason is kept with the staging verdict. Naming a path stages one file without the flag.

resolve settles an in-progress merge, rebase, or cherry-pick. It classifies every conflicted path at once, regenerates once instead of once per file, settles the files one side deleted (which no VCS invokes a merge driver for), and stages everything the regeneration touched so a following commit or rebase --continue does not refuse on a dirty tree. Conflicts in files magus does not generate are reported and left alone. Pass --against <ref> to merge that ref first and settle what it conflicts with; add --dry-run to see the classification and have the merge backed out again.

merge-driver is the per-file driver git and hg invoke during a merge. You do not run it by hand; it is wired per clone, because a driver registration cannot be committed. That is also why a forge reports conflicts your own clone would settle silently, and why resolve exists as the bulk counterpart.

checkpoint prints the identity of the working state right now - head revision, branch, whether the tree is dirty, and a digest of the uncommitted patch. Record one when you hand a piece of work out, so a later reader knows what that work was looking at. By default it RESOLVES AND RECORDS and never MINTS: no tag, no stash, no ref, no file, nothing changed anywhere, so a checkpoint nobody keeps has cost nothing. Feed the revision to anything that takes one; compare two digests to learn whether two workers saw the same uncommitted tree, which the revision alone cannot say.

--preserve is the one thing that mints. An identity says whether two trees match; it cannot rebuild either one. --preserve additionally captures the uncommitted work - tracked edits and untracked files alike - and prints a handle that gets it back, using each backend's own mechanism: a commit under refs/magus/preserved for git, a kept shelf for Mercurial, a commit Sapling keeps hidden, and for Jujutsu the working-copy commit it already holds. The working copy is untouched either way.

Retention differs per backend. On git and Mercurial a capture is dropped at 30 days, by two passes that cover each other's gap: every preserve prunes, which bounds a repository nothing schedules against, and the server's prune-preserved job prunes on its own, which reaches a repository preserved once and never again. That job is a no-op with no server running, so on a machine that runs none the standalone spelling is magus server prune-preserved.

Sapling drops nothing either way: magus mints a hidden commit there, and no Sapling command removes one without discarding the working copy, so those stay until you remove them. List them with sl log --hidden -r "desc('magus preserved working copy')". Jujutsu mints nothing, so nothing accumulates.

resolve works on git, Mercurial and Jujutsu. Only --against is git-only: merge the base in yourself on the others, then run resolve.

vcs add options

--reason string
Why the undeclared files belong in this change; required with --untracked, kept with the staging verdict
--untracked
Also stage undeclared files; requires --reason

vcs resolve options

--against ref
Merge this `ref` first, then settle what it conflicts with

vcs checkpoint options

--preserve
Also capture the uncommitted work and print a handle that restores it

Subcommands

add
Stage a change the way this workspace's declarations say it should be staged
resolve
Settle an in-progress merge's conflicted generated files, then regenerate once
checkpoint
Print the working state's identity, for recording what a lease was handed; writes nothing unless --preserve
merge-driver
The per-file merge driver git and hg invoke; you do not run this by hand

Examples

Stage a change without sweeping in build residue

magus vcs add

Classify the dirty tree, stage nothing

magus vcs add --dry-run

Sweep in the undeclared files, on the record

magus vcs add --untracked --reason "new fixtures the go spell does not claim"

Settle a conflicted merge

magus vcs resolve

Merge the base in and settle it in one step

magus vcs resolve --against origin/main

Record what a lease was handed

magus vcs checkpoint

The one citable token, for a ledger cell

magus vcs checkpoint -o name

Capture the uncommitted work too, before something risky

magus vcs checkpoint --preserve

See Also

magus(1), magus-ls(1), magus-describe(1), magus-run(1), magus-x(1), magus-where(1), magus-affected(1), magus-graph(1), magus-query(1), magus-explain(1), magus-path(1), magus-refs(1), magus-watch(1), magus-events(1), magus-status(1), magus-clean(1), magus-shell(1), magus-queue(1), magus-doctor(1), magus-config(1), magus-session(1), magus-memory(1), magus-job(1), magus-notes(1), magus-diff(1), magus-server(1), magus-broker(1), magus-mcp(1), magus-buzz(1), magus-completion(1), magus-man(1), magus-init(1), magus-spell(1), magus-agent(1), magus-self(1), magus-version(1)

ManpagePages in this section. magus brokerCheck or stop the broker: the per-user process that holds this host's concurrency slots, declared memory and shared services, which a run starts on its own. magus mcpServe the MCP tools over stdin and stdout for the agent host that launched the process, against the workspace it was launched in, with no server and no token. magus selfManage the magus binary in place, with a self-update subcommand supporting version pinning, dry-run, downgrade, and out-of-tree install directories, plus registry data refresh and the mgs shorthand.
generatedinternal/cli/registry.goclimagus vcsgitmergeconflictsgenerated filesstaging
Last updated (95680f58)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. See workspace.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). See operations.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. See affected.

Broker

The per-user background process that holds this host's capacity: the machine budget every run claims slots from, and the shared services runs keep warm. A run starts it on demand; broker: off in magus.yaml runs without one. See server.

Server

The background process a person starts with magus server start. It serves MCP, the console, background jobs and the warm knowledge graph, and adopts nested magus calls into one pool. See server.

CI

An ordinary magusfile-defined target you compose yourself with magus\needs - magus does not hardcode its stages. Magus.RunCI treats it specially only in that it strips the rw charm, it is the anchor magus affected ci keys off, and a selected scope with no project declaring it is a load error rather than a silent no-op. See targets.

MAGUS.md

The committed routing index at a workspace root, regenerated from the knowledge graph: it lists every node and points at the exact query for a given question, so it is the entry point an agent reads first. See knowledge.

Session

An agent host's conversation, by the id the host delivers to its hooks. magus never mints one: a record with no session is unattributed, and the OS user it carries says whose account ran it.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.