gitbutlerapp/gitbutler · info

well-formed root ref

Error message

well-formed root ref

What it means

Panic from `expect("well-formed root ref")` after `"HEAD".try_into()` in `apply.rs:1069` (but-workspace). It converts the literal string `HEAD` into a gix partial ref name for a RefEdit that updates HEAD (deref mode) when there is no workspace ref to point at. Parsing the fixed string `HEAD` cannot fail under gix's validation rules, so this is a static-invariant assertion, not a runtime risk.

Source

Thrown at crates/but-workspace/src/branch/apply.rs:1069

fn set_head_to_reference(
    repo: &gix::Repository,
    new_ref_target: gix::ObjectId,
    new_ref: Option<&gix::refs::FullNameRef>,
) -> anyhow::Result<()> {
    let edits = match new_ref {
        None => {
            let head_message = "GitButler checkout workspace during apply-branch".into();
            vec![RefEdit {
                change: Change::Update {
                    log: LogChange {
                        mode: RefLog::AndReference,
                        force_create_reflog: false,
                        message: head_message,
                    },
                    expected: PreviousValue::Any,
                    new: Target::Object(new_ref_target),
                },
                name: "HEAD".try_into().expect("well-formed root ref"),
                deref: true,
            }]
        }
        Some(new_ref) => {
            // This also means we want HEAD to point to it.
            let head_message = "GitButler switch to workspace during apply-branch".into();
            vec![
                RefEdit {
                    change: Change::Update {
                        log: LogChange {
                            mode: RefLog::AndReference,
                            force_create_reflog: false,
                            message: head_message,
                        },
                        expected: PreviousValue::Any,
                        new: Target::Symbolic(new_ref.to_owned()),
                    },
                    name: "HEAD".try_into().expect("well-formed root ref"),

View on GitHub (pinned to caf1f223d3)

Solutions

1. No action needed — the literal is valid by construction
2. If patching this area, keep the string `HEAD` or reuse gix's existing HEAD name constant instead of re-parsing

When it happens

Trigger: Executed on the apply-branch path where no `new_ref` exists and HEAD must be moved directly to the new workspace target; would only panic if the literal were changed to something that is not a valid ref name.

Common situations: None in stock builds; only forks or hand-edited patches that alter the literal.

Related errors

• well-formed root ref
• known statically
• AtSegment anchor always has oldest commit resolved
• a committed transaction always materializes a workspace
• if it was found before it will be found as id

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