facebook/docusaurus · error

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

Error message

Failed to retrieve the git history for file "${file}" with exit code ${result.exitCode}: ${result.stderr}

What it means

Thrown by getFileCommitDate() after git log exits with a non-zero code. The error includes the exit code and the contents of stderr captured by execa, which usually reveals why git refused. This is a generic 'git itself failed' branch distinct from 'file not tracked' (empty output) and 'unexpected output' (regex miss).

Source

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

        // Do not include GPG signature in the log output
        // See https://github.com/facebook/docusaurus/pull/10022
        '-c',
        'log.showSignature=false',
        'log',
        `--format=${resultFormat}`,
        '--max-count=1',
        ...(age === 'oldest' ? ['--follow', '--diff-filter=A'] : []),
        '--',
        path.basename(file),
      ],
      {
        cwd: path.dirname(file),
      },
    );
  }))!;

  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.`,
    );
  }

View on GitHub (pinned to 3f483e80e3)

Solutions

  1. Read the stderr echoed in the error message — it is git's own explanation of the failure.
  2. If the index is locked ('.git/index.lock' exists), remove the stale lock file or abort the in-progress rebase/merge.
  3. For corrupted history, re-clone the repository or run `git fsck --full` to diagnose and repair.
  4. If running in CI, clear the cached checkout workspace so a fresh clone is performed.

Example fix

# before — stale index.lock from an interrupted rebase
# error: Another git process seems to be running in this repository

# after
rm -f .git/index.lock
git rebase --abort  # if a rebase is in progress
# then re-run the build
Defensive patterns

Strategy: try-catch

Validate before calling

import fs from 'fs-extra';

async function repoLooksHealthy(repoDir: string): Promise<boolean> {
  return fs.pathExists(path.join(repoDir, '.git'))
    && !await fs.pathExists(path.join(repoDir, '.git', 'index.lock'));
}

if (!(await repoLooksHealthy(repoDir))) {
  throw new Error('Repository looks unhealthy (missing .git or stale index.lock).');
}

Try / catch

try {
  await getFileCommitDate(file, { age: 'newest' });
} catch (err) {
  if (err instanceof Error && err.message.includes('with exit code')) {
    // err message carries git's stderr; repair the repo or clear CI cache
  }
  throw err;
}

Prevention

When it happens

Trigger: Running git log inside getFileCommitDate where the repository state causes git to fail: a corrupted .git directory, an interrupted rebase leaving the index locked, an unreadable git object, or a permission error reading the repo. Less commonly, an execa-level issue (signal kill, max buffer) surfaces as a non-zero exit.

Common situations: A shallow clone with broken history references. A repo mid-rebase or mid-merge with a locked index. Disk/permission errors on .git internals. A CI environment with a corrupted checkout cache. Concurrent git processes racing on the same repo (mitigated by GitCommandQueue but not eliminated).

Related errors

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