jdx/mise · error

a branch name is required

Error message

a branch name is required

What it means

resolve_branch, which picks the git branch for dotfiles history sync setup, ended with no branch: none was requested, no branch is already connected for this machine on that repository, and no fallback could be determined, so publishing has no target and setup aborts.

Solutions

1. Pass a concrete branch name: `mise dot origin set <url> --branch main`
2. Omit `--branch` to reuse the currently connected branch or the default resolution
3. Fix the shell variable supplying the branch name

Example fix

// before
mise dot origin set <url> --branch "$BRANCH"  # empty
// after
mise dot origin set <url> --branch main

let branch = std::env::var("BRANCH").unwrap_or_default();
if branch.trim().is_empty() {
    eprintln!("BRANCH is empty; pass --branch <name> or omit the flag");
    std::process::exit(2);
}

match result {
    Err(e) if e.to_string().contains("a branch name is required") => eprintln!("usage: mise dot origin set <url> --branch <name>"),
    _ => {}
}

When it happens

Trigger: `mise dot origin set --branch " "` or `--branch ""` — the flag is present but its value trims to empty; `resolve_branch` is called from set_inner.

Common situations: An unset shell variable interpolated into `--branch "$B"`; copy-paste dropping the branch name; quoting issues passing an empty string.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• a repository url is required
• repos: command is required
• adoption requires confirmation; review the directory and…
• at least one target or --changed is required
• Either --url or --platform-url must be specified

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/773e6a9d25ee5361. Report an issue: GitHub.

Appendix: source

Thrown at src/system/history/sync/origin.rs:247

    // written: fetch-only connects without publishing anything
    let outcome = run::sync(&store, &tracked, &SyncRequest::new(!opts.mode.publishes()))?;
    report(&outcome);
    Ok(())
}

/// The setup branch: the one asked for, else the branch this machine already
/// follows on the same repository, else the repository's own default branch.
/// Assuming `main` reads a repository that does not have it as empty, and
/// publishes an unrelated root branch beside its real history.
fn resolve_branch(
    remote: &Remote<'_>,
    requested: Option<&str>,
    connected: Option<&str>,
) -> Result<String> {
    if let Some(branch) = requested {
        let branch = branch.trim();
        if branch.is_empty() {
            bail!("a branch name is required");
        }
        return Ok(branch.to_string());
    }
    if let Some(branch) = connected {
        return Ok(branch.to_string());
    }
    // an unreachable repository is reported by the fetch that follows
    Ok(super::onboard::default_branch(remote)?.unwrap_or_else(|| DEFAULT_BRANCH.to_string()))
}

/// A missing branch is only an empty repository when the repository has no
/// branches at all; otherwise connecting would publish an unrelated root
/// branch beside the history that is already there.
pub(super) fn refuse_missing_branch(remote: &Remote<'_>, branch: &str, url: &str) -> Result<()> {
    // a listing that fails must not read as an empty repository: that is the
    // path this check exists to prevent
    let refs = remote.ls_remote()?;
    let heads: Vec<&str> = refs

View on GitHub (pinned to 533346cc37)