GitoxideLabs/gitoxide · error

amending requires exactly one selected path

Error message

amending requires exactly one selected path

What it means

Amending the head commit via `perform_inner` accepts exactly one selected path; if `Kind::Amend` is combined with a `selected_paths` list containing any number of paths other than one, the operation is rejected. This enforces that amend-with-paths is a single-path operation in tix.

Solutions

1. Select exactly one path when amending, or drop the path selection to amend the whole staged tree.
2. Use the spill operation (`Kind::Spill`) if the intent is to move multiple paths.
3. Perform multiple amend operations, one per path, if each path must be folded separately.

Example fix

// before (two paths selected)
head::perform(&repo, Kind::Amend, Some((&[path_a, path_b], group)), ...)?;
// after
head::perform(&repo, Kind::Amend, Some((&[path_a], group)), ...)?;

if kind == Kind::Amend {
    match selected_paths {
        Some((paths, _)) if paths.len() != 1 => {
            anyhow::bail!("amend takes exactly one selected path (got {})", paths.len());
        }
        _ => {}
    }
}

match result {
    Err(e) if e.to_string().contains("amending requires exactly one selected path") => {
        eprintln!("select a single path, or use spill for multiple paths");
    }
    other => other?,
}

When it happens

Trigger: Calling `perform`/`perform_with_changes`/`perform_reporting`/`amend_index`/`amend_index_reporting` with `kind == Kind::Amend` and `selected_paths = Some((paths, _))` where `paths.len() != 1` (zero or multiple paths).

Common situations: Selecting several changed paths in the UI/script and issuing an amend; passing an empty selection with amend; CLI plumbing that forwards the wrong selection kind.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot run without any task to perform on the repositories
• At least one operation failed
• No commits to process
• Refusing to checkout index into existing directory
• Cannot print information using 'human' format.

AI-assisted analysis of GitoxideLabs/gitoxide@e73179060b (2026-09-08). Data as JSON: /api/errors/31c59c565538b01c. Report an issue: GitHub.

Appendix: source

Thrown at gix-tix/src/edit/head.rs:89

        .context("could not find HEAD commit")?
        .decode()
        .context("could not decode HEAD commit")?
        .into_owned()
        .context("could not own HEAD commit")?;
    repo.workdir().context("editing HEAD requires a worktree")?;
    repo.commit_signing_options_if_enabled()
        .context("could not resolve commit signing configuration")?;
    repo = repo.with_object_memory();
    let old_tree = commit.tree;
    let pending = rebase::is_pending(&commit);
    let review = super::review::is_review(&commit);
    let parent_tree = match commit.parents.first().copied() {
        Some(parent) => repo.find_commit(parent)?.tree_id()?.detach(),
        None => repo.empty_tree().id,
    };
    let selected_amend_path = match (kind, selected_paths) {
        (Kind::Amend, Some(([path], _))) => Some(path),
        (Kind::Amend, Some(_)) => anyhow::bail!("amending requires exactly one selected path"),
        _ => None,
    };
    let tree = match kind {
        Kind::Spill => match selected_paths {
            Some((paths, selected_parent)) => {
                spill_paths_tree(&repo, old_tree, selected_parent.unwrap_or(parent_tree), paths)?
            }
            None => parent_tree,
        },
        Kind::Amend => {
            let index = repo.index_or_empty().context("could not load the index")?;
            if index
                .entries()
                .iter()
                .any(|entry| entry.stage() != gix::index::entry::Stage::Unconflicted)
            {
                anyhow::bail!("cannot amend with unresolved index conflicts");
            }

View on GitHub (pinned to e73179060b)