GitoxideLabs/gitoxide · error

git checkout failed with

Error message

git checkout failed with {}: {}

What it means

This variant of the `checkout` failure includes the captured stderr from the `git checkout` subprocess: tix ran `git checkout`, it exited non-zero, and stderr contained a message. The error propagates git's own diagnostic (e.g. 'error: pathspec ... did not match') alongside the exit status.

Solutions

1. Read the stderr in the error message — it contains git's exact reason — and fix that underlying issue.
2. Verify the target ref/commit exists with `git rev-parse <ref>` before checkout.
3. Commit or stash local modifications that git reports as blocking the checkout.
4. If the object is missing (shallow/partial clone), fetch it first (`git fetch --unshallow` or deepen).

Example fix

// before
checkout(&repo, &["checkout", "feature/typo-name"])?;
// -> "git checkout failed with exit status: 1: error: pathspec 'feature/typo-name' did not match"

// after
let branch = "feature/correct-name";
if repo.find_reference(&format!("refs/heads/{branch}")).is_ok() {
    checkout(&repo, &["checkout", branch])?;
}

repo.rev_parse_single(target)
    .with_context(|| format!("target {target} does not resolve"))?;
if repo.is_dirty().unwrap_or(false) {
    anyhow::bail!("commit or stash changes before checkout");
}

if let Err(e) = checkout(&repo, &["checkout", target]) {
    let msg = e.to_string();
    if let Some(stderr) = msg.splitn(2, ": ").nth(1) {
        eprintln!("git said: {stderr}"); // act on git's own diagnostic
    }
    return Err(e);
}

When it happens

Trigger: Calling `checkout_review_return_reporting`, `checkout_branch`, `checkout_pin`, or `checkout_detached` with a ref/commit that git rejects — nonexistent branch, invalid object id, blocked by local modifications, or detached HEAD to an invalid pin.

Common situations: Typo in branch name; checking out a pin before it was created; uncommitted local changes colliding with the target ref; trying to checkout a commit not in the object database (shallow clone).

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

• git checkout failed with
• Refusing to checkout index into existing directory
• One or more errors occurred - checkout is incomplete
• One or more errors occurred - checkout is incomplete
• Command failed

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

Appendix: source

Thrown at gix-tix/src/edit/time_travel.rs:1342

    )
}

pub(super) fn checkout(workdir: &Path, args: impl IntoIterator<Item = OsString>) -> Result<()> {
    let output = Command::new("git")
        .arg("-C")
        .arg(workdir)
        .arg("checkout")
        .args(args)
        .output()
        .context("could not launch git checkout")?;
    if output.status.success() {
        return Ok(());
    }
    let stderr = output.stderr.trim().to_str_lossy();
    if stderr.is_empty() {
        anyhow::bail!("git checkout failed with {}", output.status)
    }
    anyhow::bail!("git checkout failed with {}: {}", output.status, stderr)
}

fn contains(repository: &gix::Repository, ancestor: ObjectId, descendant: ObjectId) -> bool {
    ancestor == descendant
        || repository
            .merge_base(ancestor, descendant)
            .is_ok_and(|base| base.as_ref() == ancestor)
}

pub(crate) fn pin_label(pin: &history::Pin) -> String {
    format!(
        "pin:{}",
        pin.name
            .as_bstr()
            .strip_prefix(history::PIN_PREFIX)
            .unwrap_or(pin.name.as_bstr())
            .to_str_lossy()
    )

View on GitHub (pinned to e73179060b)