jdx/mise · error

--operation takes at most one checkpoint reference

Error message

--operation takes at most one checkpoint reference

What it means

In `dotfiles history diff`, `--operation` mode compares two checkpoints derived from history operations and therefore accepts at most one explicit checkpoint reference (the second endpoint defaults to the latest matching entry). Passing two references (`a` and `b`) together with `--operation` is unsupported and throws this error.

Source

Thrown at src/cli/dotfiles/history/diff.rs:54

    #[usage(long, value_name = "PATH")]
    path: Option<String>,

    /// Exit 1 when the two sides differ
    #[usage(long)]
    exit_code: bool,
}

impl HistoryDiff {
    pub(crate) async fn run(self) -> Result<()> {
        let (store, tracked, entries) = super::open().await?;
        let Some(repo) = store.repo() else {
            bail!("comparing checkpoints requires git");
        };
        let path = self.path.as_deref().map(display_arg);
        let (from, to, label) =
            if self.operation {
                if self.b.is_some() {
                    bail!("--operation takes at most one checkpoint reference");
                }
                let outcome = match &self.a {
                    Some(reference) => super::resolve(reference, &entries, None)?,
                    None => entries
                        .iter()
                        .rev()
                        .find(|entry| entry.checkpoint.operation.is_some())
                        .cloned()
                        .ok_or_else(|| eyre::eyre!("no recorded operation"))?,
                };
                let operation =
                    outcome.checkpoint.operation.as_ref().ok_or_else(|| {
                        eyre::eyre!("checkpoint {} is not an operation", outcome.id)
                    })?;
                let before = operation
                    .before
                    .as_ref()
                    .and_then(|uuid| entries.iter().find(|entry| &entry.checkpoint.uuid == uuid))

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Drop `--operation` when comparing two explicit checkpoint references.
2. Keep `--operation` and pass at most one reference; the second endpoint is resolved automatically.
3. Resolve the operation checkpoints first with `mise bootstrap dotfiles history ls` and diff them by plain checkpoint refs instead.

Example fix

// before
mise bootstrap dotfiles history diff --operation op1 op2
// after
mise bootstrap dotfiles history diff --operation op1
# or two plain refs without --operation
mise bootstrap dotfiles history diff op1 op2

# pass at most one ref when using --operation
refs=$#
if [ "$use_operation" = 1 ] && [ "$refs" -gt 1 ]; then
  echo "--operation takes at most one checkpoint reference"; exit 1
fi

When it happens

Trigger: Running `mise bootstrap dotfiles history diff --operation refA refB` — i.e. `--operation` combined with two positional checkpoint references (self.b is Some).

Common situations: Copying the two-reference syntax of normal checkpoint diffing and adding `--operation` to it; scripts that always pass two refs.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• --changed does not accept target arguments
• --source can only be used with one target
• locked mode requires lockfile to be enabled hint: Remove `lo
• at least one target or --changed is required
• `--mode track` tracks a file where it is and takes no source

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/7a3668597e5fade7. Report an issue: GitHub.