{"record":{"id":"3604141a556803c5","repo":"facebook/docusaurus","slug":"failed-to-retrieve-the-git-history-for-file-fil-360414","errorCode":null,"errorMessage":"Failed to retrieve the git history for file \"${file}\" because the file is not tracked by git.","messagePattern":"Failed to retrieve the git history for file \"(.+?)\" because the file is not tracked by git\\.","errorType":"exception","errorClass":"FileNotTrackedError","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-utils/src/vcs/gitUtils.ts","lineNumber":182,"sourceCode":"    );\n  }))!;\n\n  if (result.exitCode !== 0) {\n    throw new Error(\n      `Failed to retrieve the git history for file \"${file}\" with exit code ${result.exitCode}: ${result.stderr}`,\n    );\n  }\n\n  // We only parse the output line starting with our \"RESULT:\" prefix\n  // See why https://github.com/facebook/docusaurus/pull/10022\n  const regex = includeAuthor\n    ? /(?:^|\\n)RESULT:(?<timestamp>\\d+),(?<author>.+)(?:$|\\n)/\n    : /(?:^|\\n)RESULT:(?<timestamp>\\d+)(?:$|\\n)/;\n\n  const output = result.stdout.trim();\n\n  if (!output) {\n    throw new FileNotTrackedError(\n      `Failed to retrieve the git history for file \"${file}\" because the file is not tracked by git.`,\n    );\n  }\n\n  const match = output.match(regex);\n\n  if (!match) {\n    throw new Error(\n      `Failed to retrieve the git history for file \"${file}\" with unexpected output: ${output}`,\n    );\n  }\n\n  const timestampInSeconds = Number(match.groups!.timestamp);\n  const timestamp = timestampInSeconds * 1_000;\n  const date = new Date(timestamp);\n\n  if (includeAuthor) {\n    return {date, timestamp, author: match.groups!.author!};","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-utils/src/vcs/gitUtils.ts#L164-L200","documentation":"Thrown as a FileNotTrackedError by getFileCommitDate() when git log exits 0 but stdout is empty. An empty result means git found the file on disk but has no commit touching it — i.e. the file is untracked (never git add-ed/committed). The custom error class lets upstream code distinguish this from other failures and warn once instead of crashing per file.","triggerScenarios":"Building with showLastUpdateTime enabled for files that exist on disk but are not yet committed: newly authored docs not yet staged, generated files written outside git, files in a fresh checkout that were never added. The git log command targets path.basename(file) so any untracked file matching triggers this.","commonSituations":"Writing new docs and running the dev/build server before `git add`. Build outputs (generated Markdown) that live in the content tree but are gitignored. Cloning a repo then adding files locally without committing. A CMS or export pipeline dropping files into the docs folder without going through git.","solutions":["Stage and commit the untracked files: `git add path/to/file && git commit`.","If the files are intentionally untracked (generated, gitignored), disable showLastUpdateTime / enableUpdateTimepot so Docusaurus does not query git for them, or move them out of the content tree.","Note that getGitCommitInfo already downgrades FileNotTrackedError to a one-time warning; if you are seeing a hard error you are calling getFileCommitDate directly and should add your own try/catch.","Re-run the build after committing; the git log output will no longer be empty."],"exampleFix":"# before — new doc file is untracked\n# error: ...because the file is not tracked by git.\n\ngit add docs/new-page.md\ngit commit -m 'Add new-page'\n# then re-run the build","handlingStrategy":"try-catch","validationCode":"import { execaSync } from 'execa';\nimport path from 'path';\n\nfunction isFileTrackedByGit(file: string): boolean {\n  try {\n    return execaSync('git', ['ls-files', '--error-unmatch', path.basename(file)], { cwd: path.dirname(file) }).exitCode === 0;\n  } catch { return false; }\n}\n\nif (!isFileTrackedByGit(file)) {\n  throw new Error(`File is not tracked by git; commit it or remove it from content: ${file}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await getFileCommitDate(file, { age: 'newest' });\n} catch (err) {\n  if (err instanceof FileNotTrackedError) {\n    // file is untracked: warn once (as getGitCommitInfo does) and skip\n  }\n  throw err;\n}","preventionTips":["Commit new content files (git add + git commit) before running builds with showLastUpdateTime enabled.","Keep generated/gitignored files out of the content tree, or disable git-time features for those paths.","Remember FileNotTrackedError is downgraded to a single warning by getGitCommitInfo; only direct callers of getFileCommitDate need their own handling."],"tags":["git","untracked","warning","vcs"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}