What causes "name the paths to roll back, or `--to --all` for everything the checkpoint covers" in jdx/mise?

List the paths to roll back: `mise bootstrap dotfiles rollback ...`

name the paths to roll back, or `--to <ref> --all` for every

Error message

name the paths to roll back, or `--to <ref> --all` for everything the checkpoint covers

What it means

rollback requires the request to actually name something to restore. If paths is empty and the request is not a full `--to <ref> --all` rollback, there is no defined restore target, so mise bails with guidance on the two accepted forms. This prevents silently doing nothing or guessing the scope.

Source

Thrown at src/system/history/replay.rs:115

    /// modes git cannot express, `0600` say), and for the directories
    /// above it.
    bits: Option<u32>,
    dir_bits: Vec<(PathBuf, u32)>,
}

/// One checkpoint and the paths to take from it.
struct Target {
    entry: Entry,
    paths: Vec<PathBuf>,
}

pub(crate) async fn rollback(req: RollbackRequest) -> Result<()> {
    ensure_enabled()?;
    if req.all && !req.paths.is_empty() {
        bail!("choose explicit paths or `--all`, not both");
    }
    if req.paths.is_empty() && !(req.to.is_some() && req.all) {
        bail!(
            "name the paths to roll back, or `--to <ref> --all` for everything the checkpoint covers"
        );
    }
    if req.to.is_none() && req.all {
        bail!("`--all` needs `--to <ref>`");
    }
    let (store, tracked, entries) = crate::cli::dotfiles::history::open().await?;
    let repo = store
        .repo()
        .ok_or_else(|| eyre::eyre!("rolling back requires git"))?;
    let live = live_tree(repo, &tracked)?;
    let paths: Vec<PathBuf> = req
        .paths
        .iter()
        .map(|path| normalize_target(path))
        .collect();
    for path in &paths {
        if tracked.entry_for(path).is_none() {

View on GitHub (pinned to afd2eddd3a)

Solutions

List the paths to roll back: `mise bootstrap dotfiles rollback <path>...`
Or perform a full restore: `mise bootstrap dotfiles rollback --to <ref> --all`
Run `mise bootstrap dotfiles paths` to see tracked paths first

Example fix

// before
mise bootstrap dotfiles rollback --to abc123
// after
mise bootstrap dotfiles rollback --to abc123 --all

Defensive patterns

Strategy: validation

Validate before calling

if (req.paths.length === 0 && !(req.to && req.all)) {
  throw new Error("must specify paths, or --to <ref> --all");
}

Type guard

const hasTarget = (req: { paths: string[]; to?: string; all?: boolean }) =>
  req.paths.length > 0 || (req.to != null && req.all === true);

Try / catch

try {
  await rollback(req);
} catch (e) {
  if (String(e).includes("name the paths")) {
    console.error("usage: rollback <path>... | rollback --to <ref> --all");
  } else throw e;
}

Prevention

Make at least one of paths/--to required in the CLI parser
Default to prompting for paths when none are given interactively
Document both accepted invocation forms in help output

When it happens

Trigger: Calling rollback with no path arguments and either no --to/--all combination, e.g. `rollback` alone, `rollback --to <ref>` without --all, or `rollback --all` handled separately. Condition: req.paths.is_empty() && !(req.to.is_some() && req.all).

Common situations: Users run `mise bootstrap dotfiles rollback` expecting an interactive picker; scripts forget the path argument; users pass --to without --all thinking a ref alone defines scope.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

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