execa v10

Author: slorber

packages/create-docusaurus/src/commands.ts

@@ -7,7 +7,6 @@
 
 // We use cross-spawn instead of spawn because of Windows compatibility issues.
 // For example, "yarn" doesn't work on Windows, it requires "yarn.cmd"
-// Tools like execa() use cross-spawn under the hood, and "resolve" the command
 import crossSpawn from 'cross-spawn';
 import supportsColor from 'supports-color';
 import {

packages/docusaurus-utils/src/vcs/__tests__/gitUtils.test.ts

@@ -9,7 +9,7 @@ import {describe, expect, it} from 'vitest';
 import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
-import execa from 'execa';
+import {execa, type Options, type Result} from 'execa';
 
 import {
   FileNotTrackedError,
@@ -38,22 +38,13 @@ class Git {
     cwd: string;
     args: string[];
     cmd: string;
-    options?: execa.Options;
-  }): Promise<execa.ExecaReturnValue> {
-    const res = await execa(cmd, args, {
+    options?: Options;
+  }): Promise<Result> {
+    return execa(cmd, args, {
       cwd,
-      silent: true,
       shell: true,
       ...options,
     });
-    if (res.exitCode !== 0) {
-      throw new Error(
-        `Git command failed with code ${res.exitCode}: ${cmd} ${args.join(
-          ' ',
-        )}`,
-      );
-    }
-    return res;
   }
 
   static async initializeRepo(dir: string): Promise<Git> {
@@ -83,8 +74,8 @@ class Git {
   async runOptimisticGitCommand(
     cmd: string,
     args?: string[],
-    options?: execa.Options,
-  ): Promise<execa.ExecaReturnValue> {
+    options?: Options,
+  ): Promise<Result> {
     return Git.runOptimisticGitCommand({cwd: this.dir, cmd, args, options});
   }
 
@@ -538,8 +529,10 @@ describe('submodules APIs', () => {
         [Error: Couldn't find the git superproject root directory
         Failure while running \`git rev-parse --show-superproject-working-tree\` from cwd="<HOME_DIR>"
         The command executed throws an error: Command failed with exit code 128: git rev-parse --show-superproject-working-tree
+
         fatal: not a git repository (or any of the parent directories): .git]
-        Cause: [Error: Command failed with exit code 128: git rev-parse --show-superproject-working-tree
+        Cause: [ExecaError: Command failed with exit code 128: git rev-parse --show-superproject-working-tree
+
         fatal: not a git repository (or any of the parent directories): .git]
       `);
     });

packages/docusaurus-utils/src/vcs/gitUtils.ts

@@ -9,7 +9,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import os from 'os';
 import _ from 'lodash';
-import execa from 'execa';
+import {execa, execaSync} from 'execa';
 import PQueue from 'p-queue';
 import logger from '@docusaurus/logger';
 
@@ -34,7 +34,7 @@ const GitCommandQueue = new PQueue({
 
 const realHasGitFn = () => {
   try {
-    return execa.sync('git', ['--version']).exitCode === 0;
+    return execaSync('git', ['--version']).exitCode === 0;
   } catch {
     return false;
   }
@@ -164,12 +164,6 @@ export async function getFileCommitDate(
     );
   }))!;
 
-  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
@@ -294,15 +288,6 @@ The command executed throws an error: ${error.message}`,
     );
   });
 
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `${createErrorMessageBase()}
-The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
-        result.stderr,
-      )}`,
-    );
-  }
-
   return fs.realpath.native(result.stdout.trim());
 }
 
@@ -334,15 +319,6 @@ The command executed throws an error: ${error.message}`,
     );
   });
 
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `${createErrorMessageBase()}
-The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
-        result.stderr,
-      )}`,
-    );
-  }
-
   const output = result.stdout.trim();
   // this command only works when inside submodules
   // otherwise it doesn't return anything when we are inside the main repo
@@ -372,15 +348,6 @@ The command executed throws an error: ${error.message}`,
     );
   });
 
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `${createErrorMessageBase()}
-The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
-        result.stderr,
-      )}`,
-    );
-  }
-
   const output = result.stdout.trim();
 
   if (!output) {
@@ -461,20 +428,13 @@ export async function getGitRepositoryFilesInfo(
     ],
     {
       cwd,
-      encoding: 'utf-8',
+      encoding: 'utf8',
       // TODO use streaming to avoid a large buffer
       // See https://github.com/withastro/starlight/issues/3154
       maxBuffer: 20 * 1024 * 1024,
     },
   );
 
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `Docusaurus failed to run the 'git log' to retrieve tracked files last update date/author.
-The command exited with code ${result.exitCode}: ${result.stderr}`,
-    );
-  }
-
   const logLines = result.stdout.split('\n');
 
   const now = Date.now();

packages/docusaurus/bin/beforeCli.mjs

@@ -112,14 +112,12 @@ export default async function beforeCli() {
       }
 
       const yarnVersionResult = await execa`yarn --version`;
-      if (yarnVersionResult.exitCode === 0) {
-        const majorVersion = parseInt(
-          yarnVersionResult.stdout?.trim().split('.')[0] ?? '',
-          10,
-        );
-        if (!Number.isNaN(majorVersion)) {
-          return majorVersion;
-        }
+      const majorVersion = parseInt(
+        yarnVersionResult.stdout?.trim().split('.')[0] ?? '',
+        10,
+      );
+      if (!Number.isNaN(majorVersion)) {
+        return majorVersion;
       }
 
       return undefined;

packages/docusaurus/src/commands/deploy.ts

@@ -9,7 +9,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import os from 'os';
 import logger from '@docusaurus/logger';
-import execa from 'execa';
+import {execa} from 'execa';
 import {hasSSHProtocol, buildSshUrl, buildHttpsUrl} from '@docusaurus/utils';
 import {loadContext, type LoadContextParams} from '../server/site';
 import {build} from './build/build';
@@ -30,14 +30,16 @@ const debugMode = !!process.env.DOCUSAURUS_DEPLOY_DEBUG;
 
 // Log executed commands so that user can figure out mistakes on his own
 // for example: https://github.com/facebook/docusaurus/issues/3875
-function exec(cmd: string, options?: {log?: boolean; failfast?: boolean}) {
+async function exec(
+  file: string,
+  args: string[],
+  options?: {log?: boolean; failfast?: boolean},
+) {
   const log = options?.log ?? true;
-  const failfast = options?.failfast ?? false;
+  const failfast = options?.failfast ?? true;
+  const cmd = [file, ...args].join(' ');
   try {
-    // TODO migrate to execa(file,[...args]) instead
-    //  Use async/await everything
-    //  Avoid execa.command: the args need to be escaped manually
-    const result = execa.commandSync(cmd);
+    const result = await execa(file, args, {reject: false});
     if (log || debugMode) {
       logger.info`code=${obfuscateGitPass(
         cmd,
@@ -48,7 +50,8 @@ function exec(cmd: string, options?: {log?: boolean; failfast?: boolean}) {
     }
     if (failfast && result.exitCode !== 0) {
       throw new Error(
-        `Command returned unexpected exitCode ${result.exitCode}`,
+        `Command returned unexpected exitCode ${result.exitCode}
+${result.stderr}`,
       );
     }
     return result;
@@ -63,14 +66,8 @@ In CWD code=${process.cwd()}`,
   }
 }
 
-// Execa escape args and add necessary quotes automatically
-// When using Execa.command, the args containing spaces must be escaped manually
-function escapeArg(arg: string): string {
-  return arg.replaceAll(' ', '\\ ');
-}
-
-function hasGit() {
-  return exec('git --version').exitCode === 0;
+async function hasGit() {
+  return (await exec('git', ['--version'], {failfast: false})).exitCode === 0;
 }
 
 export async function deploy(
@@ -93,26 +90,22 @@ This behavior can have SEO impacts and create relative link issues.
   }
 
   logger.info('Deploy command invoked...');
-  if (!hasGit()) {
+  if (!(await hasGit())) {
     throw new Error('Git not installed or not added to PATH!');
   }
 
   // Source repo is the repo from where the command is invoked
-  const {stdout} = exec('git remote get-url origin', {
+  const {stdout} = await exec('git', ['remote', 'get-url', 'origin'], {
     log: false,
-    failfast: true,
   });
   const sourceRepoUrl = stdout.trim();
 
   // The source branch; defaults to the currently checked out branch
   const sourceBranch =
     process.env.CURRENT_BRANCH ??
-    exec('git rev-parse --abbrev-ref HEAD', {
-      log: false,
-      failfast: true,
-    })
-      ?.stdout?.toString()
-      .trim();
+    (
+      await exec('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {log: false})
+    ).stdout.trim();
 
   const gitUser = process.env.GIT_USER;
 
@@ -157,10 +150,7 @@ This behavior can have SEO impacts and create relative link issues.
   const isPullRequest =
     process.env.CI_PULL_REQUEST ?? process.env.CIRCLE_PULL_REQUEST;
   if (isPullRequest) {
-    exec('echo "Skipping deploy on a pull request."', {
-      log: false,
-      failfast: true,
-    });
+    logger.info('Skipping deploy on a pull request.');
     process.exit(0);
   }
 
@@ -225,7 +215,9 @@ You can also set the deploymentBranch property in docusaurus.config.js .`);
 
   // Save the commit hash that triggers publish-gh-pages before checking
   // out to deployment branch.
-  const currentCommit = exec('git rev-parse HEAD')?.stdout?.toString().trim();
+  const currentCommit = (
+    await exec('git', ['rev-parse', 'HEAD'])
+  ).stdout.trim();
 
   const runDeploy = async (outputDirectory: string) => {
     const targetDirectory = cliOptions.targetDir ?? '.';
@@ -238,22 +230,26 @@ You can also set the deploymentBranch property in docusaurus.config.js .`);
     // Clones the repo into the temp folder and checks out the target branch.
     // If the branch doesn't exist, it creates a new one based on the
     // repository default branch.
-    if (
-      exec(
-        `git clone --depth 1 --branch ${deploymentBranch} ${deploymentRepoURL} ${escapeArg(
-          toPath,
-        )}`,
-      ).exitCode !== 0
-    ) {
-      exec(`git clone --depth 1 ${deploymentRepoURL} ${escapeArg(toPath)}`);
-      exec(`git checkout -b ${deploymentBranch}`);
+    const cloneResult = await exec(
+      'git',
+      [
+        'clone',
+        '--depth',
+        '1',
+        '--branch',
+        deploymentBranch,
+        deploymentRepoURL,
+        toPath,
+      ],
+      {failfast: false},
+    );
+    if (cloneResult.exitCode !== 0) {
+      await exec('git', ['clone', '--depth', '1', deploymentRepoURL, toPath]);
+      await exec('git', ['checkout', '-b', deploymentBranch]);
     }
 
     // Clear out any existing contents in the target directory
-    exec(`git rm -rf ${escapeArg(targetDirectory)}`, {
-      log: false,
-      failfast: true,
-    });
+    await exec('git', ['rm', '-rf', targetDirectory], {log: false});
 
     const targetPath = path.join(toPath, targetDirectory);
     try {
@@ -262,32 +258,37 @@ You can also set the deploymentBranch property in docusaurus.config.js .`);
       logger.error`Copying build assets from path=${fromPath} to path=${targetPath} failed.`;
       throw err;
     }
-    exec('git add --all', {failfast: true});
+    await exec('git', ['add', '--all']);
 
     const gitUserName = process.env.GIT_USER_NAME;
     if (gitUserName) {
-      exec(`git config user.name ${escapeArg(gitUserName)}`, {failfast: true});
+      await exec('git', ['config', 'user.name', gitUserName]);
     }
 
     const gitUserEmail = process.env.GIT_USER_EMAIL;
     if (gitUserEmail) {
-      exec(`git config user.email ${escapeArg(gitUserEmail)}`, {
-        failfast: true,
-      });
+      await exec('git', ['config', 'user.email', gitUserEmail]);
     }
 
     const commitMessage =
       process.env.CUSTOM_COMMIT_MESSAGE ??
       `Deploy website - based on ${currentCommit}`;
-    const commitResults = exec(
-      `git commit -m ${escapeArg(commitMessage)} --allow-empty`,
+    // The commit might return a non-zero value when site is up to date.
+    const commitResults = await exec(
+      'git',
+      ['commit', '-m', commitMessage, '--allow-empty'],
+      {failfast: false},
+    );
+    const pushResult = await exec(
+      'git',
+      ['push', '--force', 'origin', deploymentBranch],
+      {failfast: false},
     );
-    if (exec(`git push --force origin ${deploymentBranch}`).exitCode !== 0) {
+    if (pushResult.exitCode !== 0) {
       throw new Error(
         'Running "git push" command failed. Does the GitHub user account you are using have push access to the repository?',
       );
     } else if (commitResults.exitCode === 0) {
-      // The commit might return a non-zero value when site is up to date.
       let websiteURL;
       if (githubHost === 'github.com') {
         websiteURL = projectName.includes('.github.io')
@@ -297,7 +298,7 @@ You can also set the deploymentBranch property in docusaurus.config.js .`);
         // GitHub enterprise hosting.
         websiteURL = `https://${githubHost}/pages/${organizationName}/${projectName}/`;
       }
-      exec(`echo "Website is live at ${websiteURL}."`, {failfast: true});
+      logger.success`Website is live at url=${websiteURL}.`;
       process.exit(0);
     }
   };