{"record":{"id":"a5cf630cd1a2a73a","repo":"coleam00/Archon","slug":"cannot-adopt-worktreepath-git-pointer-is-not","errorCode":null,"errorMessage":"Cannot adopt ${worktreePath}: .git pointer is not a git-worktree reference.","messagePattern":"Cannot adopt (.+?): \\.git pointer is not a git-worktree reference\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/git/src/worktree.ts","lineNumber":479,"sourceCode":"  let worktreeIdentity: GitCheckoutIdentity;\n  let expectedIdentity: GitCheckoutIdentity;\n  try {\n    [worktreeIdentity, expectedIdentity] = await Promise.all([\n      getGitCheckoutIdentity(worktreePath),\n      getGitCheckoutIdentity(expectedRepo),\n    ]);\n  } catch (error) {\n    throw new Error(\n      `Cannot verify worktree ownership at ${worktreePath}: ${(error as Error).message}`,\n      {\n        cause: error,\n      }\n    );\n  }\n  if (!worktreeIdentity.linkedWorktree) {\n    // Not a git-worktree pointer (e.g., submodule pointer, or malformed).\n    // We cannot confirm this is our worktree, so refuse adoption.\n    throw new Error(`Cannot adopt ${worktreePath}: .git pointer is not a git-worktree reference.`);\n  }\n\n  // Compare resolved common-directory paths: the primary checkout and every\n  // linked worktree share this Git identity, while separate clones differ.\n  if (resolve(worktreeIdentity.commonGitDir) !== resolve(expectedIdentity.commonGitDir)) {\n    throw new Error(\n      `Worktree at ${worktreePath} belongs to a different clone (${worktreeIdentity.commonGitDir}). ` +\n        'Remove it from that clone or use a different codebase registration.'\n    );\n  }\n}\n","sourceCodeStart":461,"sourceCodeEnd":491,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/git/src/worktree.ts#L461-L491","documentation":"verifyWorktreeOwnership refuses to adopt a directory whose .git pointer does not identify it as a git linked worktree (worktreeIdentity.linkedWorktree is falsy). This covers submodule .git pointers, plain directories, or malformed pointers where ownership cannot be confirmed, so the safe behavior is to refuse adoption.","triggerScenarios":"Calling findExisting/assertWorktreeOwnership on a path that contains a .git directory (a full independent clone) or a submodule-style .git file instead of a `gitdir: ...` worktree pointer, so getGitCheckoutIdentity returns no linkedWorktree.","commonSituations":"Someone ran `git clone` into the worktree path separately; a directory created by cloning rather than `git worktree add`; a submodule checkout sitting where the worktree is expected; hand-crafted or truncated .git files.","solutions":["Delete or move the non-worktree directory and create a proper one with `git worktree add <path> <branch>`.","If the directory is a separate clone you want to use, register that clone as its own codebase instead of adopting it as a worktree.","Inspect the .git entry: it must be a file containing `gitdir: <repo>/.git/worktrees/<name>` for adoption to succeed.","If it was a submodule checkout, initialize it through its parent repo rather than treating it as a worktree."],"exampleFix":"// before: independent clone at the worktree path\ngit clone /srv/clone /srv/app  # .git is a directory, not a worktree pointer\n// after: proper linked worktree\nrm -rf /srv/app && cd /srv/clone && git worktree add /srv/app feat-branch","handlingStrategy":"validation","validationCode":"import { statSync, readFileSync } from 'node:fs';\nfunction isLinkedWorktreePointer(p: string): boolean {\n  const dotGit = `${p}/.git`;\n  try {\n    return statSync(dotGit).isFile() && readFileSync(dotGit, 'utf8').startsWith('gitdir:');\n  } catch { return false; }\n}\nif (!isLinkedWorktreePointer(worktreePath)) {\n  throw new Error(`${worktreePath} is not a linked worktree; recreate with git worktree add`);\n}","typeGuard":"function isLinkedWorktree(p: string): boolean {\n  const dotGit = `${p}/.git`;\n  try { return statSync(dotGit).isFile(); } catch { return false; }\n}","tryCatchPattern":"try {\n  await assertWorktreeOwnership(worktreePath, expectedRepo);\n} catch (e) {\n  if (e.message.includes('not a git-worktree reference')) {\n    console.error('Directory is a clone/submodule, not a worktree; recreate it');\n  } else throw e;\n}","preventionTips":["Never `git clone` into a path reserved for a worktree.","Initialize submodules outside worktree-reserved directories.","Check the .git entry is a `gitdir:` file before reusing an existing directory."],"tags":["git","worktree","ownership","adoption"],"backgroundTag":"worktree-ownership-unverifiable","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}