gitbutlerapp/gitbutler · error

Cannot create alias ' ': it conflicts with a built-in…

Error message

Cannot create alias '{name}': it conflicts with a built-in command

What it means

Validation in the alias add command: the requested alias name collides with a built-in 'but' subcommand (checked via is_known_subcommand), which would make the alias unresolvable or shadow real commands. Choose a different alias name that is not a known subcommand.

Solutions

1. Choose an alias name that is not a built-in `but` subcommand (e.g. `bc` instead of `commit`).
2. Run `but --help` to list reserved subcommand names before adding the alias.
3. If you meant to change the command's behavior, that requires changing but itself, not an alias.

Example fix

// before
but alias add commit "mcp commit --all"
// after
but alias add c "mcp commit --all"

const BUILTIN = ['init','status','commit','push','pull','branch','mcp','agent','config','alias'];
if (BUILTIN.includes(aliasName)) throw new Error(`Alias '${aliasName}' conflicts with a built-in command; pick another name`);

When it happens

Trigger: Calling `but alias add <name> <value>` (add in crates/but/src/command/alias.rs) with a name for which crate::alias::is_known_subcommand(name) returns true — e.g. `but alias add commit ...` or `but alias add push ...`.

Common situations: Users porting git alias habits (e.g. aliasing `co`, `commit`) to but; typos intended as alias values being placed in the name position.

Related errors

• Aborting due to empty branch name
• Aborting due to empty
• CLI destination must be absolute
• CLI source ' ' must be an executable file
• CLI source path must be absolute

AI-assisted analysis of gitbutlerapp/gitbutler@58e5313667 (2026-09-18). Data as JSON: /api/errors/ffb31ef03fed89cb. Report an issue: GitHub.

Appendix: source

Thrown at crates/but/src/command/alias.rs:221

    user_aliases
}

/// Get all default aliases
fn get_default_aliases() -> Vec<(String, String)> {
    crate::alias::get_all_default_aliases()
}

/// Add a new alias
pub fn add(
    ctx: Option<&Context>,
    out: &mut OutputChannel,
    name: &str,
    value: &str,
    global: EditGlobalConfig,
) -> Result<()> {
    // Validate alias name doesn't conflict with known commands
    if crate::alias::is_known_subcommand(name) {
        anyhow::bail!("Cannot create alias '{name}': it conflicts with a built-in command");
    }

    let is_global: bool = global.into();
    let repo = ctx.map(|ctx| ctx.repo.get()).transpose()?;
    edit_git_config(repo.as_deref(), global, |config| {
        set_alias(config, name, value)?;
        Ok(())
    })?;

    if let Some(out) = out.for_human() {
        let t = theme::get();
        writeln!(
            out,
            "{} Alias '{}' {} '{}'",
            t.sym().success,
            t.config_key.paint(name),
            t.sym().arrow,
            t.config_value.paint(value)

View on GitHub (pinned to 58e5313667)