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. 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.
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
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
- 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
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-doctor(1), magus-config(1), magus-session(1), magus-memory(1), magus-notes(1), magus-diff(1), magus-server(1), magus-mcp(1), magus-buzz(1), magus-completion(1), magus-man(1), magus-init(1), magus-agent(1), magus-self(1), magus-version(1)