Add options to ignore stdErr or stdOut in the timeout plugin

Author: steveukx

docs/PLUGIN-TIMEOUT.md

@@ -25,3 +25,32 @@ catch (err) {
     }
 }
 ```
+
+## Task Timeouts and Progress Events
+
+The default behaviour of the timeout plugin is to listen for data being received on both the
+`stdOut` and `stdErr` streams from the `git` child process.
+
+When using the `progress` plugin, `git` will be streaming regular progress updates to `stdErr`,
+so you may see that the timeout is never reached and `simple-git` patiently waits for `git` to
+finish whatever it is doing.
+
+Configure this with the optional `stdOut` and `stdErr` properties of the `timeout` plugin
+configuration:
+
+```typescript
+import { simpleGit, GitPluginError, SimpleGit, SimpleGitProgressEvent } from "simple-git";
+
+const git: SimpleGit = simpleGit({
+   baseDir: "/some/path",
+   progress({method, stage, progress}) {
+      console.log(`git.${method} ${stage} stage ${progress}% complete`);
+   },
+   timeout: {
+      block: 2000,
+      stdOut: true, // default behaviour, resets the 2s timer every time data arrives on stdOut
+      stdErr: false // custom behaviour, ignore the progress events being written to stdErr
+   }
+});
+
+```

simple-git/src/lib/plugins/timout-plugin.ts

@@ -5,6 +5,8 @@ import { GitPluginError } from '../errors/git-plugin-error';
 
 export function timeoutPlugin({
    block,
+   stdErr = true,
+   stdOut = true,
 }: Exclude<SimpleGitOptions['timeout'], undefined>): SimpleGitPlugin<'spawn.after'> | void {
    if (block > 0) {
       return {
@@ -30,8 +32,8 @@ export function timeoutPlugin({
                context.kill(new GitPluginError(undefined, 'timeout', `block timeout reached`));
             }
 
-            context.spawned.stdout?.on('data', wait);
-            context.spawned.stderr?.on('data', wait);
+            stdOut && context.spawned.stdout?.on('data', wait);
+            stdErr && context.spawned.stderr?.on('data', wait);
             context.spawned.on('exit', stop);
             context.spawned.on('close', stop);
 

simple-git/src/lib/types/index.ts

@@ -105,6 +105,18 @@ export interface SimpleGitPluginConfig {
        * content on the stdOut/stdErr streams before forcibly closing the git process.
        */
       block: number;
+
+      /**
+       * Reset timeout plugin after receiving data on `stdErr` - set to `false` to ignore
+       * `stdErr` content when determining whether to kill the process (defaults to `true`).
+       */
+      stdErr?: boolean;
+
+      /**
+       * Reset timeout plugin after receiving data on `stdOut` - set to `false` to ignore
+       * `stdOut` content when determining whether to kill the process (defaults to `true`).
+       */
+      stdOut?: boolean;
    };
 
    spawnOptions: Pick<SpawnOptions, 'uid' | 'gid'>;

simple-git/test/integration/timeout-progress-combo.spec.ts

@@ -1,25 +1,29 @@
-import {promiseError} from "@kwsites/promise-result";
-import {assertGitError, createTestContext, newSimpleGit, SimpleGitTestContext} from "@simple-git/test-utils";
+import { promiseError } from '@kwsites/promise-result';
+import {
+   assertGitError,
+   createTestContext,
+   newSimpleGit,
+   SimpleGitTestContext,
+} from '@simple-git/test-utils';
 
-import {GitPluginError} from '../..';
+import { GitPluginError, SimpleGitOptions } from '../..';
 
 describe('timeout-progress-combo', () => {
-
    let context: SimpleGitTestContext;
    const url = 'https://github.com/nodejs/node';
-   const progress = ({method, stage, progress}) => {
-      console.log(`git.${method} ${stage} stage ${progress}% complete`);
-   };
-   const timeout = {
+   const progress: SimpleGitOptions['progress'] = jest.fn();
+   const timeout: SimpleGitOptions['timeout'] = {
       block: 5000,
+      stdOut: true,
+      stdErr: false,
    };
 
    jest.setTimeout(10 * 1000);
 
    beforeEach(async () => (context = await createTestContext()));
 
    it('succeeds', async () => {
-      const options = {
+      const options: Partial<SimpleGitOptions> = {
          baseDir: context.root,
          timeout,
          progress,
@@ -38,5 +42,4 @@ describe('timeout-progress-combo', () => {
       const threw = await promiseError(newSimpleGit(options).clone(url));
       assertGitError(threw, 'block timeout reached', GitPluginError);
    });
-
 });