Enter your search text in the box above

Select a result to preview

Mutations Documented Dry-Run First

#resources #resources/writing #resources/programming

Mutations documented dry-run first

Every example that calls a mutating command shows --dry-run before --yes. The doc discipline mirrors the runtime contract.

The pairing

# Preview the deletion:
mxr archive --search 'older_than:1y AND from:newsletter' --dry-run

# Apply it:
mxr archive --search 'older_than:1y AND from:newsletter' --yes

Two blocks, in that order. The reader sees the safe form first and the destructive form second. Copy-paste habits absorb the discipline.

Why this matters in docs specifically

A doc that shows the destructive form first is teaching a bad habit. Readers paste examples from docs; if the example is destructive without preview, that's what gets pasted. The doc author is responsible for the muscle memory the doc instills.

This is the same discipline mxr expects of agents writing mutations. The same code path must produce the same selection in --dry-run and --yes — otherwise the preview lies. The doc convention enforces the runtime convention from the reader's side.

Callouts for irreversible operations

Some mutations don't get a dry-run because they're irreversible:

:::caution[This is irreversible]
The reset wipes local state. There's no `--dry-run` because there's nothing to preview.
:::

The caution exists because the safe pairing doesn't apply. Make the absence of dry-run visible, don't just leave it implicit.

The broader pattern

Anywhere a tool ships with a preview mode and an execute mode, the docs lead with preview. Anywhere it ships without one, the docs flag the destructive operation explicitly. The convention is: the reader never executes a destructive operation by accident from a doc.

See also