gitbutlerapp/gitbutler · error

Ambiguous branch identifier '{}'. Did you mean one of: {}

Error message

Ambiguous branch identifier '{}'. Did you mean one of:
{}

What it means

When the argument parses to more than one CLI id in the IdMap and at least one is a branch, `resolve_branch_name` refuses to guess and lists the matching branch names via `format_branch_suggestions`. Abbreviated numeric ids or shared name prefixes are the usual cause.

Source

Thrown at crates/but/src/command/legacy/push.rs:1129

                "Branch '{}' not found. Available branches:\n{}",
                branch_id,
                format_branch_suggestions(&available_branches)
            ));
        }
        return Ok(branch_id.to_string());
    }

    if cli_ids.len() > 1 {
        let branch_names: Vec<String> = cli_ids
            .iter()
            .filter_map(|id| match id {
                CliId::Branch(branch) => Some(branch.name.clone()),
                _ => None,
            })
            .collect();

        if !branch_names.is_empty() {
            return Err(anyhow::anyhow!(
                "Ambiguous branch identifier '{}'. Did you mean one of:\n{}",
                branch_id,
                format_branch_suggestions(&branch_names)
            ));
        } else {
            return Err(anyhow::anyhow!(
                "Identifier '{branch_id}' matches multiple non-branch items. Please use a branch name or branch CLI ID."
            ));
        }
    }

    match &cli_ids[0] {
        CliId::Branch(branch) => Ok(branch.name.clone()),
        _ => Err(anyhow::anyhow!(
            "Expected branch identifier, got {}. Please use a branch name or branch CLI ID.",
            cli_ids[0].kind_for_humans()
        )),
    }

View on GitHub (pinned to caf1f223d3)

Solutions

  1. Use the full, unique branch name shown in the 'Did you mean one of' list
  2. Lengthen an abbreviated id until it matches exactly one item
  3. Re-check current ids with `but status` before scripting them

Example fix

# before
but push 12
# error: Ambiguous branch identifier '12'. Did you mean one of: ...

# after
but push feature-x   # full unique name from the suggestion list
Defensive patterns

Strategy: validation

Validate before calling

# Before scripting a short id, ensure it resolves to exactly one branch
but status | grep -c "$id"   # more than one hit -> use the full unique name instead

Try / catch

// Extract the 'Did you mean one of:' candidates from the failure
let err = String::from_utf8_lossy(&out.stderr).to_string();
if err.contains("Ambiguous branch identifier") {
    let candidates: Vec<&str> = err.lines().skip_while(|l| !l.contains("Did you mean")).skip(1).collect();
    // let the user disambiguate, then retry with the full name
}

Prevention

When it happens

Trigger: Passing an abbreviated CLI id (e.g. `but push 12`) that matches several branches, or a name/prefix that resolves to multiple workspace branches.

Common situations: Long-lived workspaces accumulate similarly named branches (feature-x, feature-x-2); short ids from `but status` reused after new branches shifted the numbering.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@caf1f223d3 (2026-08-20). Data as JSON: /api/errors/495ed22a29f8ee2f. Report an issue: GitHub.