fix(content-docs): warn when files are not tracked

.cspell.json

@@ -33,5 +33,6 @@
     "versioned_docs",
     "*.min.*"
   ],
-  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"]
+  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"],
+  "words": ["dbaeumer", "devcontainers", "esbenp", "orta", "unmatch"]
 }

.devcontainer/devcontainer.json

@@ -1,10 +1,33 @@
 {
-  "name": "Docusaurus Dev Container",
-  "image": "mcr.microsoft.com/vscode/devcontainers/typescript-node:14-buster",
+  "image": "mcr.microsoft.com/vscode/devcontainers/base:ubuntu-20.04",
   "settings": {
-    "terminal.integrated.shell.linux": "/bin/bash"
+    "[typescript]": {
+      "editor.defaultFormatter": "esbenp.prettier-vscode",
+      "editor.formatOnSave": true
+    },
+    "[json]": {
+      "editor.defaultFormatter": "esbenp.prettier-vscode",
+      "editor.formatOnSave": true
+    },
+    "[jsonc]": {
+      "editor.defaultFormatter": "esbenp.prettier-vscode",
+      "editor.formatOnSave": true
+    }
   },
-  "extensions": ["dbaeumer.vscode-eslint", "orta.vscode-jest"],
+  "extensions": [
+    "dbaeumer.vscode-eslint",
+    "orta.vscode-jest",
+    "esbenp.prettier-vscode",
+    "streetsidesoftware.code-spell-checker"
+  ],
   "forwardPorts": [3000],
-  "postCreateCommand": "yarn install"
+  "containerUser": "vscode",
+  "postCreateCommand": "yarn install",
+  "waitFor": "postCreateCommand", // otherwise automated jest tests fail
+  "features": {
+    "node": {
+      "version": "14"
+    },
+    "github-cli": "latest"
+  }
 }

jest.config.mjs

@@ -7,6 +7,8 @@
 
 import {fileURLToPath} from 'url';
 
+process.env.TZ = 'UTC';
+
 const ignorePatterns = [
   '/node_modules/',
   '__fixtures__',

package.json

@@ -52,7 +52,7 @@
     "lint:spelling": "cspell \"**\" --no-progress",
     "lint:style": "stylelint \"**/*.css\"",
     "lerna": "lerna",
-    "test": "cross-env TZ=UTC jest",
+    "test": "jest",
     "test:build:website": "./admin/scripts/test-release.sh",
     "watch": "yarn lerna run --parallel watch",
     "clear": "(yarn workspace website clear || echo 'Failure while running docusaurus clear') && yarn lerna exec --ignore docusaurus yarn rimraf lib lib-next",

packages/docusaurus-plugin-content-blog/src/blogUtils.ts

@@ -247,7 +247,7 @@ async function processBlogSourceFile(
       });
       return result.date;
     } catch (err) {
-      logger.error(err);
+      logger.warn(err);
       return (await fs.stat(blogSourceAbsolute)).birthtime;
     }
   }

packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts

@@ -47,7 +47,7 @@ describe('getFileLastUpdate', () => {
 
   it('non-existing file', async () => {
     const consoleMock = jest
-      .spyOn(console, 'error')
+      .spyOn(console, 'warn')
       .mockImplementation(() => {});
     const nonExistingFileName = '.nonExisting';
     const nonExistingFilePath = path.join(
@@ -65,10 +65,17 @@ describe('getFileLastUpdate', () => {
     consoleMock.mockRestore();
   });
 
-  it('temporary created file that has no git timestamp', async () => {
+  it('temporary created file that is not tracked by git', async () => {
+    const consoleMock = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => {});
     const tempFilePath = path.join(__dirname, '__fixtures__', '.temp');
     await fs.writeFile(tempFilePath, 'Lorem ipsum :)');
     await expect(getFileLastUpdate(tempFilePath)).resolves.toBeNull();
+    expect(consoleMock).toHaveBeenCalledTimes(1);
+    expect(consoleMock).toHaveBeenLastCalledWith(
+      expect.stringMatching(/not tracked by git./),
+    );
     await fs.unlink(tempFilePath);
   });
 

packages/docusaurus-plugin-content-docs/src/lastUpdate.ts

@@ -6,11 +6,16 @@
  */
 
 import logger from '@docusaurus/logger';
-import {getFileCommitDate, GitNotFoundError} from '@docusaurus/utils';
+import {
+  getFileCommitDate,
+  FileNotTrackedError,
+  GitNotFoundError,
+} from '@docusaurus/utils';
 
 type FileLastUpdateData = {timestamp?: number; author?: string};
 
 let showedGitRequirementError = false;
+let showedFileNotTrackedError = false;
 
 export async function getFileLastUpdate(
   filePath?: string,
@@ -31,8 +36,16 @@ export async function getFileLastUpdate(
     if (err instanceof GitNotFoundError && !showedGitRequirementError) {
       logger.warn('Sorry, the docs plugin last update options require Git.');
       showedGitRequirementError = true;
+    } else if (
+      err instanceof FileNotTrackedError &&
+      !showedFileNotTrackedError
+    ) {
+      logger.warn(
+        'Cannot infer the update date for some files, as they are not tracked by git.',
+      );
+      showedFileNotTrackedError = true;
     } else {
-      logger.error(err);
+      logger.warn(err);
     }
     return null;
   }

packages/docusaurus-utils/src/gitUtils.ts

@@ -5,11 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/* eslint-disable max-classes-per-file */
+
 import path from 'path';
 import shell from 'shelljs';
 
 export class GitNotFoundError extends Error {}
 
+export class FileNotTrackedError extends Error {}
+
 export const getFileCommitDate = (
   file: string,
   {
@@ -39,6 +43,18 @@ export const getFileCommitDate = (
   const fileBasename = path.basename(file);
   const fileDirname = path.dirname(file);
 
+  if (
+    shell.exec(`git ls-files --error-unmatch -- "${fileBasename}"`, {
+      // cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
+      cwd: fileDirname,
+      silent: true,
+    }).code !== 0
+  ) {
+    throw new FileNotTrackedError(
+      `Failed to retrieve git history for "${file}" because the file is not tracked by git.`,
+    );
+  }
+
   let formatArg = '--format=%ct';
   if (includeAuthor) {
     formatArg += ',%an';

packages/docusaurus-utils/src/index.ts

@@ -21,7 +21,11 @@ export {
   WEBPACK_URL_LOADER_LIMIT,
 } from './constants';
 export {generate, genChunkName, readOutputHTMLFile} from './emitUtils';
-export {getFileCommitDate, GitNotFoundError} from './gitUtils';
+export {
+  getFileCommitDate,
+  FileNotTrackedError,
+  GitNotFoundError,
+} from './gitUtils';
 export {
   mergeTranslations,
   updateTranslationFileMessages,