gitbutlerapp/gitbutler · info

known statically

Error message

known statically

What it means

Panic from `expect("known statically")` after `gix::refs::FullName::try_from(WORKSPACE_REF_NAME)` in `apply.rs:359` (but-workspace). It parses a compile-time constant (the default GitButler workspace ref name) into a validated `FullName`. Because the constant is fixed and valid, the conversion cannot fail in a released build; the expect is a compile-time-known invariant, not a runtime risk.

Source

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

        );
    }
    // In general, we only have to deal with one branch to apply. But when we are on an adhoc workspace,
    // we need to assure both branches go into the existing or the new workspace:
    //  - the current one and the one to apply, if these are different.
    // The returned workspace ref name will be set to the new merge commit, if created, or it may not change
    // at all if the workspace can be created by just setting metadata.
    let (workspace_ref_name_to_update, branches_to_apply) = match &ws.kind {
        WorkspaceKind::Managed { ref_info }
        | WorkspaceKind::ManagedMissingWorkspaceCommit { ref_info } => {
            (ref_info.ref_name.clone(), vec![branch.clone()])
        }
        WorkspaceKind::AdHoc => {
            // We need to switch over to a possibly existing workspace.
            // We know that the current branch is *not* reachable from the workspace or isn't naturally included,
            // so it needs to be added as well.
            let next_ws_ref_name = match workspace_reference_naming {
                WorkspaceReferenceNaming::Default => {
                    gix::refs::FullName::try_from(WORKSPACE_REF_NAME).expect("known statically")
                }
                WorkspaceReferenceNaming::Given(name) => name,
            };
            let mut current_unmanaged_head_branch_name = ws.ref_name().map(|rn| rn.to_owned());
            if let Some(ref current_head_ref) = current_unmanaged_head_branch_name {
                // If our current branch is related to the next workspace's target, don't add it to the
                // soon-to-be-created workspace.
                // This is a 'trick' to allow callers to prevent 'main' to be added to the workspace automatically
                // even though the new workspace is supposed to have it as target.
                if ws.is_branch_the_target_or_its_local_tracking_branch(current_head_ref.as_ref()) {
                    current_unmanaged_head_branch_name.take();
                }
            }

            (
                next_ws_ref_name,
                current_unmanaged_head_branch_name
                    .into_iter()

View on GitHub (pinned to caf1f223d3)

Solutions

1. No action needed for stock GitButler — this cannot fire with the shipped constant
2. If you forked and changed WORKSPACE_REF_NAME, validate it is a fully-qualified ref like `refs/gitbutler/workspace` and covered by a unit test
3. Prefer `WorkspaceReferenceNaming::Given(name)` at the API boundary instead of editing the constant

Example fix

// before
const WORKSPACE_REF_NAME: &str = "refs/heads/gitbutler/workspace"; // valid

// after: guard forks with a test
#[test]
fn workspace_ref_name_is_valid() {
    gix::refs::FullName::try_from(WORKSPACE_REF_NAME).expect("known statically");
}

// Only relevant for forks that change the constant:
#[test]
fn default_workspace_ref_name_parses() {
    assert!(gix::refs::FullName::try_from(WORKSPACE_REF_NAME).is_ok());
}

When it happens

Trigger: Only fires if `WORKSPACE_REF_NAME` is edited to a string that is not a valid fully-qualified ref name (empty, missing the `refs/` prefix, containing invalid bytes or `..`); applying a branch when the workspace kind is `AdHoc` and `WorkspaceReferenceNaming::Default` is used, which is the normal path that executes this parse.

Common situations: Forks that rename the workspace ref constant; patching the constant via a config value at build time; none in stock GitButler.

Related errors

• well-formed root ref
• well-formed root ref
• a committed transaction always materializes a workspace
• AtSegment anchor always has oldest commit resolved
• 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/b9b437c3adb387ff. Report an issue: GitHub.