fix(docs): warn when files are not tracked

facebook · Mar 18, 2022 · 5fa76ed · 5fa76ed
1 parent a1d333e
commit 5fa76ed
Show file tree

Hide file tree

Showing 7 changed files with 57 additions and 9 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -33,5 +33,6 @@
     "versioned_docs",
     "*.min.*"
   ],
-  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"]
+  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"],
+  "words": ["dbaeumer", "devcontainers", "esbenp", "orta", "unmatch"]
 }
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -2,9 +2,25 @@
   "name": "Docusaurus Dev Container",
   "image": "mcr.microsoft.com/vscode/devcontainers/typescript-node:14-buster",
   "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"
 }
diff --git a/packages/docusaurus-plugin-content-blog/src/blogUtils.ts b/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;
     }
   }

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/lastUpdate.test.ts b/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(

diff --git a/packages/docusaurus-plugin-content-docs/src/lastUpdate.ts b/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,14 @@ export async function getFileLastUpdate(
     if (err instanceof GitNotFoundError && !showedGitRequirementError) {
       logger.warn('Sorry, the docs plugin last update options require Git.');
       showedGitRequirementError = true;
-    } else {
-      logger.error(err);
+    } 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;
     }
     return null;
   }

diff --git a/packages/docusaurus-utils/src/gitUtils.ts b/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';

diff --git a/packages/docusaurus-utils/src/index.ts b/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,