gitbutlerapp/gitbutler · info

well-formed root ref

Error message

well-formed root ref

What it means

Panic from `expect("well-formed root ref")` on `"HEAD".try_into()` during unapply-branch (but-workspace unapply.rs:434), where HEAD is repointed symbolically to the workspace ref after a branch was removed. As with the apply.rs twins, the parsed string is the fixed literal `HEAD`, which gix always accepts, so this expect documents a compile-time certainty rather than a runtime failure mode.

Source

Thrown at crates/but-workspace/src/branch/unapply.rs:434

            .find_reference(workspace_ref_name)?
            .peel_to_id()?
            .detach();
        ensure!(
            actual_workspace_ref_id == expected_workspace_ref_id,
            "BUG: workspace ref '{}' points to {actual_workspace_ref_id}, expected {expected_workspace_ref_id}",
            workspace_ref_name.shorten()
        );
        repo.edit_reference(RefEdit {
            change: Change::Update {
                log: LogChange {
                    mode: RefLog::AndReference,
                    force_create_reflog: false,
                    message: "GitButler switch to workspace during unapply-branch".into(),
                },
                expected: PreviousValue::Any,
                new: Target::Symbolic(workspace_ref_name.to_owned()),
            },
            name: "HEAD".try_into().expect("well-formed root ref"),
            deref: false,
        })?;
        Ok(())
    }

    /// Update the managed workspace reference after metadata has removed the branch.
    ///
    /// If the remaining applied stacks still need a workspace merge commit, this rebuilds it in
    /// memory first, then safely checks out the resulting tree and moves the workspace ref.
    /// Workspace merge conflicts are errors and leave refs, metadata, index, and worktree
    /// untouched.
    ///
    /// `ws` is the workspace projection after the branch was removed from workspace metadata.
    /// `ws_md` is the metadata that produced that projection. `repo` is the repository whose
    /// workspace ref and worktree may be updated. `workspace_ref_name` is the managed workspace
    /// ref to move to the new workspace commit. `disposition` controls whether an unnecessary
    /// workspace merge commit is kept or not.
    fn update_workspace_ref_after_unapply(

View on GitHub (pinned to caf1f223d3)

Solutions

1. No action needed
2. Keep the `HEAD` literal or a pre-parsed constant when patching this area

When it happens

Trigger: Unapplying a branch while HEAD sits inside the workspace, triggering the symbolic-HEAD switch edit; panics only if the literal is changed to an invalid ref name in a fork.

Common situations: None in stock builds.

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/f399a7bf9fb04bd8. Report an issue: GitHub.