{"record":{"id":"3ded09747413d4d9","repo":"facebook/docusaurus","slug":"couldn-t-find-the-git-repository-root-directory-fa-3ded09","errorCode":null,"errorMessage":"Couldn't find the git repository root directory\nFailure while running ${logger.code('git rev-parse --show-toplevel')} from cwd=${logger.path(cwd)}\nThe command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(result.stderr)}","messagePattern":"Couldn't find the git repository root directory\nFailure while running (.+?) from cwd=(.+?)\nThe command returned exit code (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/docusaurus-utils/src/vcs/gitUtils.ts","lineNumber":298,"sourceCode":"    return `Couldn't find the git repository root directory\nFailure while running ${logger.code(\n      'git rev-parse --show-toplevel',\n    )} from cwd=${logger.path(cwd)}`;\n  };\n\n  const result = await execa('git', ['rev-parse', '--show-toplevel'], {\n    cwd,\n  }).catch((error) => {\n    // We enter this rejection when cwd is not a dir for example\n    throw new Error(\n      `${createErrorMessageBase()}\nThe command executed throws an error: ${error.message}`,\n      {cause: error},\n    );\n  });\n\n  if (result.exitCode !== 0) {\n    throw new Error(\n      `${createErrorMessageBase()}\nThe command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(\n        result.stderr,\n      )}`,\n    );\n  }\n\n  return fs.realpath.native(result.stdout.trim());\n}\n\n// A Git \"superproject\" is a Git repository that contains submodules\n// See https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---show-superproject-working-tree\n// See https://git-scm.com/book/en/v2/Git-Tools-Submodules\nexport async function getGitSuperProjectRoot(\n  cwd: string,\n): Promise<string | null> {\n  const createErrorMessageBase = () => {\n    return `Couldn't find the git superproject root directory","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-utils/src/vcs/gitUtils.ts#L280-L316","documentation":"Thrown by getGitRepoRoot when `git rev-parse --show-toplevel` runs successfully but returns a non-zero exit code, which is git's signal that cwd is not inside any git worktree. This is distinct from error 100 (spawn/rejection) and fires only when git itself ran and decided there is no enclosing repo.","triggerScenarios":"Calling getGitRepoRoot from a path that is not inside any git repository (no `.git` upward), or inside a worktree whose `.git` pointer is broken. Transitively hit whenever Docusaurus's eager git VCS initializes on a non-repo directory.","commonSituations":"Building Docusaurus from a freshly unpacked tarball/zip with no `.git`, running `docusaurus build` in `/tmp`, vendoring the site source without the git history, or a corrupted `.git` after a botched clone.","solutions":["Move/clone the site into a real git checkout and re-run from there.","If git info is unwanted, set the VCS preset to a non-git provider via DOCUSAURUS_VCS.","Repair the repo: `git rev-parse --show-toplevel` must succeed from your cwd before invoking Docusaurus.","In CI, ensure `actions/checkout` (or equivalent) ran before the build step."],"exampleFix":"// before\n// running `docusaurus build` in /tmp/site with no .git\n// after\ngit clone https://github.com/org/site && cd site && docusaurus build","handlingStrategy":"validation","validationCode":"import {execSync} from 'child_process';\nfunction isInGitWorktree(cwd: string): boolean {\n  try {\n    execSync('git rev-parse --show-toplevel', {cwd, stdio: 'ignore'});\n    return true;\n  } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  const root = await getGitRepoRoot(cwd);\n} catch (e) {\n  if (/Couldn't find the git repository root/.test(String(e))) {\n    // not in a repo — disable git-backed VCS or clone first\n  } else throw e;\n}","preventionTips":["Always launch the build from inside the cloned checkout.","In CI, use actions/checkout before the build step.","For tarball-distributed sites, set a non-git VCS preset."],"tags":["git","vcs","worktree"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}