{"record":{"id":"b89624d091477dad","repo":"abhigyanpatwari/GitNexus","slug":"source-branch-name-must-not-start-with","errorCode":null,"errorMessage":"${source}: branch name must not start with \"-\".","messagePattern":"(.+?): branch name must not start with \"-\"\\.","errorType":"validation","errorClass":"GitNexusRcError","httpStatus":null,"severity":"warning","filePath":"gitnexus/src/cli/analyze-config.ts","lineNumber":182,"sourceCode":"  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('..')) {\n    throw new GitNexusRcError(`${source}: branch name must not contain \"..\".`);\n  }\n  // Git permits a backtick in a ref, but the branch is embedded inside a\n  // Markdown inline-code span in the generated AGENTS.md/CLAUDE.md regression\n  // example, where a backtick would close the span early and let the rest of\n  // the template render as instruction text. Reject it at this single\n  // chokepoint so all three tiers (CLI flag, .gitnexusrc, auto-detect via\n  // sanitizeDetectedBranch) are covered (#1996 tri-review P1).\n  if (trimmed.includes('`')) {\n    throw new GitNexusRcError(\n      `${source}: branch name must not contain a backtick (it would break the generated Markdown).`,\n    );\n  }\n  return trimmed;\n}\n","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/52924ef12c2290ceee4612526a828ec4cdf2047f/gitnexus/src/cli/analyze-config.ts#L164-L200","documentation":"On Windows, toNativeSafePath converts non-ASCII paths to an ASCII-safe form via 8.3 short names, then a junction fallback. Junctions cannot be created from a worker thread (main-thread-only fallback), so when the 8.3 short-name conversion also fails inside a worker, GitNexus warns and returns the original non-ASCII path. LadybugDB may then fail to open files under that path.","triggerScenarios":"process.platform === 'win32', NON_ASCII_RE matches the path, tryShortPath returns null (8.3 names disabled on the volume), and !isMainThread — the junction branch is unreachable, so the raw path is returned with this warn.","commonSituations":"Repos cloned under CJK/Unicode user profiles (C:\\Users\\名前\\...) on volumes where `fsutil 8dot3name` is disabled; worker threads handling DB/CSV paths inherited from a non-ASCII storage location. Frequently followed by 'Cannot open file.' errors from LadybugDB.","solutions":["Enable 8.3 short names on the volume: fsutil 8dot3name set 0 (then re-create files so short names generate)","Move the repo/storage path to pure ASCII (e.g. C:\\src\\repo)","Set GITNEXUS storage location to an ASCII directory if the repo itself cannot move","Check whether short names exist for the path: fsutil file queryshortname <file>"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const NON_ASCII_RE = /[^\\x00-\\x7f]/;\n// before spawning workers: resolve the ASCII-safe path ON THE MAIN THREAD\n// (junction fallback is main-thread-only) and hand workers the safe path\nexport const preResolveSafePath = (p: string): string => {\n  if (process.platform !== 'win32' || !NON_ASCII_RE.test(p)) return p;\n  return toNativeSafePath(p); // main thread: 8.3 short name or junction applies\n};","typeGuard":"const isAsciiPath = (p: string): boolean => !/[^\\x00-\\x7f]/.test(p);","tryCatchPattern":null,"preventionTips":["Enable 8.3 short names (fsutil 8dot3name set 0) on volumes hosting repos","Keep repo/storage paths ASCII on Windows, especially under CJK user profiles","Do path conversion on the main thread before worker dispatch, not inside workers"],"tags":["windows","non-ascii-path","worker-threads"],"backgroundTag":"non-ascii-path-windows","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"}