facebook/docusaurus · error · FileNotTrackedError

Failed to retrieve the git history for file "${file}" becaus

Error message

Failed to retrieve the git history for file "${file}" because the file is not tracked by git.

What it means

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.

Source

Thrown at packages/docusaurus-utils/src/vcs/gitUtils.ts:182

    );
  }))!;

  if (result.exitCode !== 0) {
    throw new Error(
      `Failed to retrieve the git history for file "${file}" with exit code ${result.exitCode}: ${result.stderr}`,
    );
  }

  // We only parse the output line starting with our "RESULT:" prefix
  // See why https://github.com/facebook/docusaurus/pull/10022
  const regex = includeAuthor
    ? /(?:^|\n)RESULT:(?<timestamp>\d+),(?<author>.+)(?:$|\n)/
    : /(?:^|\n)RESULT:(?<timestamp>\d+)(?:$|\n)/;

  const output = result.stdout.trim();

  if (!output) {
    throw new FileNotTrackedError(
      `Failed to retrieve the git history for file "${file}" because the file is not tracked by git.`,
    );
  }

  const match = output.match(regex);

  if (!match) {
    throw new Error(
      `Failed to retrieve the git history for file "${file}" with unexpected output: ${output}`,
    );
  }

  const timestampInSeconds = Number(match.groups!.timestamp);
  const timestamp = timestampInSeconds * 1_000;
  const date = new Date(timestamp);

  if (includeAuthor) {
    return {date, timestamp, author: match.groups!.author!};

View on GitHub (pinned to 3f483e80e3)

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.

Example fix

# before — new doc file is untracked
# error: ...because the file is not tracked by git.

git add docs/new-page.md
git commit -m 'Add new-page'
# then re-run the build

Defensive patterns

Strategy: try-catch

Validate before calling

import { execaSync } from 'execa';
import path from 'path';

function isFileTrackedByGit(file: string): boolean {
  try {
    return execaSync('git', ['ls-files', '--error-unmatch', path.basename(file)], { cwd: path.dirname(file) }).exitCode === 0;
  } catch { return false; }
}

if (!isFileTrackedByGit(file)) {
  throw new Error(`File is not tracked by git; commit it or remove it from content: ${file}`);
}

Try / catch

try {
  await getFileCommitDate(file, { age: 'newest' });
} catch (err) {
  if (err instanceof FileNotTrackedError) {
    // file is untracked: warn once (as getGitCommitInfo does) and skip
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/3604141a556803c5. Report an issue: GitHub.