magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
2 min read

worktree-remove

A deny rule by default: it refuses removing a worktree magus cannot prove holds nothing that would be lost, and names what to run instead.

What it catches

Removing a worktree magus cannot prove holds nothing that would be lost.

Why

A worktree may be where another session is working right now, and what it holds may exist nowhere else. git worktree remove passes only when every condition holds: the path is a linked worktree of this repository (per git worktree list), not the main one and not the checkout the session runs in; it has no modified, staged or untracked files (ignored files do not count); every commit its HEAD carries is on a remote-tracking ref or the base branch, or a job that finished (pass or fail) was taken in it and filed its result; no live job was taken in it; and it is not locked. The refusal names each failed condition and the command that inspects it, and --force changes nothing. Removal cannot be undone, so a fact that cannot be read refuses too: an unreadable job store, a line that does not parse, a path that is not a literal word, a removal inside a conditional or behind a wrapper. git worktree prune passes, since it only clears records of directories already gone, and git worktree remove --help and -h, alone on the line, print usage and pass. jj workspace forget stays refused: the jj driver cannot yet report a workspace's registration or which of its commits are published, so nothing proves a forget loses nothing.

Default and override

By default this rule takes the decision deny. A workspace sets it by name, in its root magusfile, to deny, advise or off:

magus\guard.builtins({"worktree-remove": "advise"})

A loosening takes effect once it is committed; a tightening applies at once.

Seeing it

A verdict names its rule in brackets, which is how you got here:

deny [worktree-remove]: ...

magus describe rule worktree-remove prints the same entry at a terminal, and magus describe rules lists every rule this workspace enforces.

See also

ReferencePages in this section. push-ungated: a push at a commit with no green gate: the person is asked, a leased worker refusedA deny rule by default: it refuses a push at a commit with no green gate: the person is asked, a leased worker refused, and names what to run instead. leased-path: a write into paths a running lease owns, by a caller that names no leaseAn advisory by default: it explains, and blocks nothing, on a write into paths a running lease owns, by a caller that names no lease. magus\guard.commandRegister one Buzz function the agent guard calls on every agent shell command, to add a deny or an advisory from your repository's own rules. magus ships the seam and no rules.
guardrulesworktree-removedeny
Last updated (1a76274f)
Earlier changes on this page (3)

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.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. See targets.

Buzz

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

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.

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.

Conventions

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