{"record":{"id":"424e29d413f9a1e7","repo":"abhigyanpatwari/GitNexus","slug":"source-branch-name-must-not-be-empty","errorCode":null,"errorMessage":"${source}: branch name must not be empty.","messagePattern":"(.+?): branch name must not be empty\\.","errorType":"validation","errorClass":"GitNexusRcError","httpStatus":null,"severity":"warning","filePath":"gitnexus/src/cli/analyze-config.ts","lineNumber":166,"sourceCode":"  for (const ch of value) {\n    const cp = ch.codePointAt(0);\n    if (cp !== undefined && isHiddenOrControl(cp)) {\n      throw new GitNexusRcError(\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 (from CLI or `.gitnexusrc`). Returns the\n * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the\n * shapes real 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 GitNexusRcError(`${source}: branch name must not be empty.`);\n  }\n  if (trimmed.length > BRANCH_MAX_LENGTH) {\n    throw new GitNexusRcError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);\n  }\n  assertNoHiddenChars(trimmed, source);\n  if (/\\s/.test(trimmed)) {\n    throw new GitNexusRcError(`${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 GitNexusRcError(\n      `${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\\\).`,\n    );\n  }\n  if (trimmed.startsWith('-')) {\n    throw new GitNexusRcError(`${source}: branch name must not start with \"-\".`);\n  }\n  if (trimmed.includes('..')) {","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/52924ef12c2290ceee4612526a828ec4cdf2047f/gitnexus/src/cli/analyze-config.ts#L148-L184","documentation":"Crash-recovery cleanup: the main DB file is missing (fresh open fails fs.access(dbPath) with a missing-file error), but sidecar files (`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`) from an interrupted run still exist and would block fresh opens indefinitely. GitNexus removes each orphan sidecar; failure to remove one is logged with its errno because the subsequent LadybugDB open may still fail.","triggerScenarios":"fs.access(dbPath) throws ENOENT while `.shadow` or `.wal.checkpoint` sidecars remain — typically after `gitnexus clean`/wipe was interrupted, the DB file was deleted manually, or a crash happened between DB-file removal and sidecar removal.","commonSituations":"An interrupted clean operation; users manually deleting the DB file but leaving companions; interrupted first-time init where the DB was never created but checkpoint sidecars appeared. After this warn, the index rebuilds from scratch.","solutions":["No action needed — removal enables the fresh open and the index rebuilds","If the 'failed to remove orphan sidecar' companion warn appears, clear whatever holds the file (antivirus, another process) and rerun","Use `gitnexus clean` rather than manual deletion so all sidecars go together","Recurring occurrences mean something keeps interrupting runs at the same phase — check disk health and crash logs"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"import fs from 'node:fs/promises';\n// when managing storage manually: remove sidecars only when the main DB is gone\nconst dbExists = await fs.access(dbPath).then(() => true, () => false);\nif (!dbExists) {\n  for (const s of [`${dbPath}.shadow`, `${dbPath}.wal.checkpoint`]) {\n    await fs.unlink(s).catch(() => {}); // ENOENT is fine\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use `gitnexus clean` instead of deleting DB files by hand","Never gate sidecar cleanup on anything other than main-DB absence (mirrors the code's own rule)","Watch for the companion 'failed to remove orphan sidecar' warn — it predicts an open failure"],"tags":["ladybugdb","sidecar","crash-recovery"],"backgroundTag":"orphaned-db-sidecar-files","analyzedSha":"52924ef12c2290ceee4612526a828ec4cdf2047f","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}