{"record":{"id":"2b5f23a4b0a2071f","repo":"abhigyanpatwari/GitNexus","slug":"source-branch-name-must-not-be-empty-git-ref","errorCode":null,"errorMessage":"${source}: branch name must not be empty.","messagePattern":"(.+?): branch name must not be empty\\.","errorType":"validation","errorClass":"InvalidBranchError","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/git-ref.ts","lineNumber":59,"sourceCode":"  for (const ch of value) {\n    const cp = ch.codePointAt(0);\n    if (cp !== undefined && isHiddenOrControl(cp)) {\n      throw new InvalidBranchError(\n        `${source}: value contains control or hidden/bidirectional characters, which are not allowed.`,\n      );\n    }\n  }\n};\n\n/**\n * Validate a user-supplied branch name. Returns the trimmed name or throws\n * {@link InvalidBranchError}. Conservative but accepts the shapes real\n * branches use (`feature/foo-bar`, `release/1.2`, `develop`).\n */\nexport function validateBranchName(value: string, source: string): string {\n  const trimmed = value.trim();\n  if (!trimmed) {\n    throw new InvalidBranchError(`${source}: branch name must not be empty.`);\n  }\n  if (trimmed.length > BRANCH_MAX_LENGTH) {\n    throw new InvalidBranchError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);\n  }\n  assertNoHiddenChars(trimmed, source);\n  if (/\\s/.test(trimmed)) {\n    throw new InvalidBranchError(`${source}: branch name must not contain whitespace.`);\n  }\n  // git ref-name rules (subset): reject characters git itself forbids in refs.\n  if (/[~^:?*[\\\\]/.test(trimmed)) {\n    throw new InvalidBranchError(\n      `${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\\\).`,\n    );\n  }\n  if (trimmed.startsWith('-')) {\n    throw new InvalidBranchError(`${source}: branch name must not start with \"-\".`);\n  }\n  // Force-refspec prefix (`git fetch origin +main` / `+refs/heads/main:…`).","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/git-ref.ts#L41-L77","documentation":"validateBranchName first trims the value and rejects it if nothing remains, throwing InvalidBranchError '<source>: branch name must not be empty.' The library requires a concrete branch name because an empty ref can never resolve in git and usually signals a missing or unset option.","triggerScenarios":"Calling validateBranchName('' or '   ', source) — e.g. a CLI flag or config field for a branch was never set, or an empty environment variable was passed through.","commonSituations":"Missing --branch flag with no default; unset BRANCH env var interpolated into an empty string; config file with `branch: \"\"`; a caller passing an unpopulated variable before assignment.","solutions":["Supply an actual branch name at the call site (flag, config field, or variable).","Add a guard before the call: if (!branch?.trim()) fail early with your own actionable message naming the missing option.","Check the config/env path that produced the empty string and set a correct default."],"exampleFix":"// before\nconst branch = process.env.BRANCH ?? '';\nvalidateBranchName(branch, 'deploy');\n// after\nconst branch = process.env.BRANCH;\nif (!branch || !branch.trim()) throw new Error('BRANCH env var must be set to a branch name');\nvalidateBranchName(branch, 'deploy');","handlingStrategy":"validation","validationCode":"if (typeof branch !== 'string' || !branch.trim()) {\n  throw new Error('Branch name is required: pass --branch or set the branch config field.');\n}","typeGuard":"const isNonEmptyBranch = (v: unknown): v is string =>\n  typeof v === 'string' && v.trim().length > 0;","tryCatchPattern":"try {\n  branch = validateBranchName(input, 'deploy');\n} catch (e) {\n  if (e instanceof InvalidBranchError && /must not be empty/.test(e.message)) {\n    throw new Error('No branch provided: set --branch or BRANCH env var.');\n  }\n  throw e;\n}","preventionTips":["Give branch options explicit defaults or fail with an actionable message when absent.","Never default branch configuration to empty string; use undefined so 'missing' is detectable.","Validate required inputs at CLI/config parse time, before side effects.","Check that env var interpolation isn't silently producing empty strings."],"tags":["git","branch-name","validation","empty-value"],"backgroundTag":"empty-required-field","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-09-15T23:29:44.066Z","contentChangedAt":"2026-09-15T23:29:44.066Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}