{"record":{"id":"d2803ed8423629a1","repo":"gitbutlerapp/gitbutler","slug":"cannot-create-reference-on-unborn-branch","errorCode":null,"errorMessage":"Cannot create reference on unborn branch '{}'","messagePattern":"Cannot create reference on unborn branch '(.+?)'","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/but-workspace/src/branch/apply.rs","lineNumber":351,"sourceCode":"            ws_ref_name.as_ref().map(|rn| rn.as_ref()),\n        )?;\n\n        // When exiting early, don't try to adjust the ws commit.\n        return Ok(Outcome {\n            workspace: ws,\n            status: OutcomeStatus::Applied,\n            workspace_ref_created: false,\n            workspace_merge: None,\n            conflicting_stacks: Vec::new(),\n            applied_branches,\n        });\n    };\n\n    if let Some(ws_ref_name) = ws.ref_name()\n        && repo.try_find_reference(ws_ref_name)?.is_none()\n    {\n        // The workspace is the probably ad-hoc, and doesn't exist, *assume* unborn.\n        bail!(\n            \"Cannot create reference on unborn branch '{}'\",\n            ws_ref_name.shorten()\n        );\n    }\n\n    if ws.has_workspace_commit_in_ancestry(repo) {\n        bail!(\"Refusing to work on workspace whose workspace commit isn't at the top\");\n    }\n\n    if meta.workspace_opt(branch.as_ref())?.is_some() {\n        bail!(\n            \"Refusing to apply a reference that already is a workspace: '{}'\",\n            branch.shorten()\n        );\n    }\n    // In general, we only have to deal with one branch to apply. But when we are on an adhoc workspace,\n    // we need to assure both branches go into the existing or the new workspace:\n    //  - the current one and the one to apply, if these are different.","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/58e5313667b857ef39a730e380af31816a7b1768/crates/but-workspace/src/branch/apply.rs#L333-L369","documentation":"During `apply`, if the workspace's reference (`ws.ref_name()`) does not exist in the repository, the workspace is assumed to be an ad-hoc/unborn workspace whose HEAD branch has never been created. Creating a reference on such an unborn branch is not supported, so the operation bails with the shortened ref name.","triggerScenarios":"Calling `apply` against a workspace whose ref (e.g. `refs/heads/main` in a fresh repo with no commits yet) cannot be found via `repo.try_find_reference`.","commonSituations":"Running GitButler operations in a freshly `git init`ed repository with zero commits; a corrupted/deleted HEAD branch; pointing the tool at an empty worktree.","solutions":["Create the initial commit on the branch first (e.g. `git commit --allow-empty -m init`) so the branch is born.","Point the workspace at an existing branch with commits instead of the unborn one.","Verify with `git rev-parse --verify <branch>` before invoking apply that the ref exists."],"exampleFix":"// before (empty repo)\nws.branch_apply(repo, &branch, ...).await?;\n// after\ngit.commit(\"HEAD\", \"init\", tree, ...)?; // or ensure repo has an initial commit first\nws.branch_apply(repo, &branch, ...).await?;","handlingStrategy":"validation","validationCode":"if let Some(ws_ref) = ws.ref_name() {\n    if repo.try_find_reference(ws_ref)?.is_none() {\n        return Err(\"workspace branch is unborn; create an initial commit first\");\n    }\n}","typeGuard":null,"tryCatchPattern":"// Rust\nif let Err(e) = ws.branch_apply(repo, branch, ...).await {\n    if e.to_string().starts_with(\"Cannot create reference on unborn branch\") {\n        eprintln!(\"initialize the repository with a first commit before applying\");\n        return Err(e);\n    }\n    return Err(e);\n}","preventionTips":["Require at least one commit before running GitButler apply operations.","Detect empty repos up front with `git rev-parse --verify HEAD`.","Guard against workflows that delete the workspace branch ref."],"tags":["git","workspace","unborn-branch","references"],"backgroundTag":"resource-not-found","analyzedSha":"58e5313667b857ef39a730e380af31816a7b1768","analyzedAt":"2026-09-18T06:50:32.052Z","contentChangedAt":"2026-09-18T06:50:32.052Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}