{"record":{"id":"463824457b95c5f1","repo":"abhigyanpatwari/GitNexus","slug":"branch-options-branch-does-not-match-the-ch","errorCode":null,"errorMessage":"--branch \"${options.branch}\" does not match the checked-out branch \"${checkedOutBranch}\". Check out \"${options.branch}\" before indexing it, or omit --branch to index the current branch.","messagePattern":"--branch \"(.+?)\" does not match the checked-out branch \"(.+?)\"\\. Check out \"(.+?)\" before indexing it, or omit --branch to index the current branch\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/run-analyze.ts","lineNumber":959,"sourceCode":"  // `storagePath` is ALWAYS the flat `.gitnexus` — content-addressed caches\n  // (parse-cache, parsedfile-store) and kuzu-migration cleanup live there and\n  // are shared across branches (#2106 KTD7).\n  const { storagePath } = getStoragePaths(repoPath);\n  const repoHasGit = hasGitDir(repoPath);\n  const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';\n  // Normalize the auto-detected branch the same way an explicit `--branch` is\n  // validated (#2106 R1): a git ref the branch-name rules forbid becomes `null`\n  // → the flat slot, matching that a later `--branch <that-ref>` query would\n  // also be rejected. A normal ref round-trips index-time/query-time labels.\n  const checkedOutBranch = repoHasGit\n    ? (sanitizeDetectedBranch(getCurrentBranch(repoPath)) ?? null)\n    : null;\n  // Analyze indexes the working tree, not an arbitrary ref. An explicit\n  // `--branch X` while a DIFFERENT branch Y is checked out would write Y's\n  // content into X's slot, corrupting X (#2106). Refuse the mismatch. Detached\n  // HEAD / non-git (checkedOutBranch === null) still allow an explicit label.\n  if (options.branch && checkedOutBranch && options.branch !== checkedOutBranch) {\n    throw new Error(\n      `--branch \"${options.branch}\" does not match the checked-out branch \"${checkedOutBranch}\". ` +\n        `Check out \"${options.branch}\" before indexing it, or omit --branch to index the current branch.`,\n    );\n  }\n  const branchLabel = options.branch ?? checkedOutBranch;\n  const placement = options.branch ? await resolveBranchPlacement(repoPath, branchLabel) : {};\n  const { lbugPath, metaPath } = getStoragePaths(repoPath, placement.branch);\n  return {\n    storagePath,\n    repoHasGit,\n    currentCommit,\n    checkedOutBranch,\n    branchLabel,\n    placement,\n    lbugPath,\n    metaPath,\n    metaDir: path.dirname(metaPath),\n  };","sourceCodeStart":941,"sourceCodeEnd":977,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/run-analyze.ts#L941-L977","documentation":"Thrown by the analyze command when the user passes --branch <X> but the repository's currently checked-out branch is <Y> (X != Y). Analyze indexes the working tree content, not an arbitrary git ref; labeling a different branch's content with the wrong branch name would corrupt the branch slot in the index (#2106). The check compares the sanitized auto-detected branch (getCurrentBranch + sanitizeDetectedBranch) against the explicit --branch value. Detached HEAD and non-git repos (checkedOutBranch === null) still allow an explicit label since there's no mismatch to detect.","triggerScenarios":"Running `gitnexus analyze --branch main` while the repo is checked out on `develop`; running `gitnexus analyze --branch feature/x` while on `main`. The mismatch is detected by comparing the explicit flag against the sanitized git-detected branch name. This prevents writing develop's file contents into main's index slot.","commonSituations":"A developer working on a feature branch who wants to index it but passes the wrong --branch name; CI that checks out a PR branch but passes the base branch name to --branch; muscle memory from a previous branch switch that hasn't happened yet; confusion about whether --branch checks out the branch (it doesn't — it only labels the index slot).","solutions":["Check out the target branch first: `git checkout <branch-name>`, then run `gitnexus analyze --branch <branch-name>`","Omit --branch entirely to index the current branch: `gitnexus analyze` — it auto-detects and labels with the checked-out branch","Verify the current branch with `git branch --show-current` before passing --branch","If you want to index a different branch without switching, use git worktree to create a separate working tree"],"exampleFix":"# before — on develop, trying to index as main\ngit checkout develop\ngitnexus analyze --branch main  # ERROR\n# after — check out the target branch first\ngit checkout main\ngitnexus analyze --branch main  # OK\n# or omit --branch entirely\ngitnexus analyze  # auto-detects current branch","handlingStrategy":"validation","validationCode":"// Verify the branch matches before calling analyze\nimport { execSync } from 'child_process';\nfunction getCheckedOutBranch(repoPath: string): string | null {\n  try {\n    return execSync('git branch --show-current', { cwd: repoPath, encoding: 'utf8' }).trim();\n  } catch {\n    return null; // non-git or detached HEAD\n  }\n}\n// Before calling analyze with --branch:\nconst current = getCheckedOutBranch(repoPath);\nif (options.branch && current && options.branch !== current) {\n  throw new Error(`Checkout ${options.branch} first, or omit --branch to index ${current}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runAnalyze(repoPath, options);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('--branch')) {\n    // Branch mismatch — guide user to checkout or omit --branch\n    console.error(e.message);\n  }\n  throw e;\n}","preventionTips":["Run `git branch --show-current` before passing --branch to verify alignment","Omit --branch entirely when you want to index the current branch — it auto-detects","In CI scripts, check out the target branch as an explicit step before calling analyze","Use git worktree for parallel branch analysis instead of switching branches in a single working tree"],"tags":["analyze","branch-mismatch","git","cli","validation"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}