{"record":{"id":"ffc8a25bfb110ba4","repo":"gitbutlerapp/gitbutler","slug":"not-currently-on-a-gitbutler-branch","errorCode":null,"errorMessage":"Not currently on a gitbutler/* branch.","messagePattern":"Not currently on a gitbutler/\\* branch\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/but/src/command/legacy/setup.rs","lineNumber":503,"sourceCode":"/// If so, returns true\n/// Otherwise, returns an error with a message indicating what is not setup.\n/// It will check:\n/// - if the repository exists\n/// - if the project is registered in GitButler\n/// - if there is a remote\n/// - if there is a default target branch set\n/// - if we're on a gitbutler/* branch\npub fn check_project_setup(ctx: &Context, perm: &RepoShared) -> anyhow::Result<bool> {\n    let (repo, ws, _) = ctx.workspace_and_db_with_perm(perm)?;\n\n    // check if we're on a gitbutler/* branch\n    let head = repo.head()?;\n    let head_name = head\n        .referent_name()\n        .map(|n| n.shorten().to_owned())\n        .unwrap_or_default();\n    if !head_name.starts_with(b\"gitbutler/\") {\n        anyhow::bail!(\"Not currently on a gitbutler/* branch.\");\n    }\n\n    // When on gitbutler/edit, the project was already set up when entering edit mode.\n    // The workspace graph built from gitbutler/edit doesn't expose the target ref or\n    // remote configuration, but both are still configured in virtual_branches.toml\n    // and will be accessible when returning to gitbutler/workspace.\n    if head_name == b\"gitbutler/edit\" {\n        return Ok(true);\n    }\n\n    // TODO(legacy): it's fine to have no target.\n    if ws.graph.project_meta.target_ref.is_none() {\n        anyhow::bail!(\"No default target branch set.\");\n    }\n\n    // check if there is a remote\n    if ws.remote_name().is_none()\n        && repo","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/caf1f223d3cfb94488c9198ad34487c6006c648f/crates/but/src/command/legacy/setup.rs#L485-L521","documentation":"Thrown by check_project_setup in crates/but/src/command/legacy/setup.rs:503 when the repository HEAD is not a gitbutler/* branch (gitbutler/workspace or gitbutler/edit). GitButler legacy commands read virtual-branch state relative to the workspace branch, so any other HEAD (a normal branch like main, a detached commit, an unborn branch) fails this precondition immediately.","triggerScenarios":"Running any legacy `but` command that calls check_project_setup(ctx, perm) while HEAD points elsewhere: after `git checkout main`, after `git checkout <sha>` (detached), in a fresh clone that never went through GitButler setup, or in a linked worktree checked out to a plain branch.","commonSituations":"User temporarily switched to a plain branch (CI, comparison, IDE integration) and re-ran a GitButler command; repository was never initialized with GitButler so no gitbutler/workspace branch exists; another git tool detached HEAD.","solutions":["Run `git checkout gitbutler/workspace` (or `gitbutler/edit`) to re-enter the workspace, then retry the command.","If no gitbutler/* branch exists, run `but setup` (or onboarding in the desktop app) to initialize the project.","Confirm which workspace branch exists with `git branch -a | grep gitbutler`.","If plain Git operation is intended, use `git` directly instead of the workspace-dependent `but` command."],"exampleFix":"# before\ngit checkout main\nbut status   # Not currently on a gitbutler/* branch.\n\n# after\ngit checkout gitbutler/workspace\nbut status","handlingStrategy":"validation","validationCode":"use gix::prelude::ReferenceExt as _;\nlet head = repo.head()?;\nlet name = head.referent_name().map(|n| n.shorten().to_owned()).unwrap_or_default();\nif !name.starts_with(b\"gitbutler/\") {\n    anyhow::bail!(\"switch to gitbutler/workspace before running GitButler commands\");\n}","typeGuard":null,"tryCatchPattern":"match check_project_setup(&ctx, &perm) {\n    Ok(set_up) => { /* proceed */ }\n    Err(err) if err.to_string().contains(\"gitbutler/*\") => {\n        eprintln!(\"run `git checkout gitbutler/workspace` and retry\");\n    }\n    Err(err) => return Err(err),\n}","preventionTips":["Always leave the repository on gitbutler/workspace when finishing plain-git work.","In scripts, assert `git symbolic-ref --short HEAD` starts with gitbutler/ before invoking `but`.","Run `but setup` once per clone so the workspace branch exists."],"tags":["git","branch","head","gitbutler","setup"],"backgroundTag":"wrong-branch-checked-out","analyzedSha":"caf1f223d3cfb94488c9198ad34487c6006c648f","analyzedAt":"2026-08-20T07:55:40.983Z","schemaVersion":2},"datasetVersion":"2026-08-23T16:17:53.355Z"}