Merge branch 'steveukx:main' into patch-1

Author: HonkingGoose

.changeset/config.json

@@ -6,5 +6,7 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": []
+  "ignore": [
+    "@simple-git/test-utils"
+  ]
 }

docs/PLUGIN-ERRORS.md

@@ -2,7 +2,7 @@
 
 By default, `simple-git` will determine that a `git` task has resulted in an error when the process exit
 code is anything other than `0` and there has been some data sent to the `stdErr` stream. Error handlers
-will be passed the content of both `stdOut` and `stdErr` concatenated together. 
+will be passed the content of both `stdOut` and `stdErr` concatenated together.
 
 To change any of this behaviour, configure the `simple-git` with the `errors` plugin with a function to be
 called after every task has been run and should return either `undefined` when the task is treated as
@@ -21,7 +21,7 @@ const git = simpleGit({
       if (error) return error;
 
       // customise the `errorCode` values to treat as success
-      if (result.errorCode === 0) {
+      if (result.exitCode === 0) {
          return;
       }
 

docs/PLUGIN-TIMEOUT.md

@@ -8,7 +8,6 @@ To handle the case where the underlying `git` processes appear to hang, configur
 import { simpleGit, GitPluginError, SimpleGit, SimpleGitProgressEvent } from 'simple-git';
 
 const git: SimpleGit = simpleGit({
-   baseDir: '/some/path', 
    timeout: {
        block: 2000,
    },
@@ -25,3 +24,55 @@ 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, SimpleGit } from "simple-git";
+
+const git: SimpleGit = simpleGit({
+   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
+   }
+});
+
+```
+
+## Absolute or Block Timeouts
+
+The timeout plugin will reset its timers whenever data is received meaning the plugin will
+only kill processes that appear to be hanging and allow intentionally long-running processes
+to continue uninterrupted.
+
+To change this default behaviour so that the plugin kills all processes after the supplied
+timeout, configure it so the plugin doesn't listen for data updates by supplying the optional
+`stdOut` and `stdErr` properties of the `timeout` plugin configuration:
+
+```typescript
+import { simpleGit, SimpleGit } from "simple-git";
+
+// create a simple-git instance that kills any process after 5s
+// whether it's still receiving data or not:
+const git: SimpleGit = simpleGit({
+   timeout: {
+      block: 5000,
+      stdOut: false,
+      stdErr: false
+   }
+});
+```

docs/PLUGIN-UNSAFE-ACTIONS.md

@@ -6,6 +6,27 @@ that any parameter sourced from user input is validated before being passed to t
 In some cases where there is an elevated potential for harm `simple-git` will throw an exception unless you have
 explicitly opted in to the potentially unsafe action.
 
+### Enabling custom upload and receive packs
+
+Instead of using the default `git-receive-pack` and `git-upload-pack` binaries to parse incoming and outgoing
+data, `git` can be configured to use _any_ arbitrary binary or evaluable script.
+
+To avoid accidentally triggering the evaluation of a malicious script when merging user provided parameters
+into command executed by `simple-git`, custom pack options (usually with the `--receive-pack` and `--upload-pack`)
+are blocked without explicitly opting into their use  
+
+```typescript
+import { simpleGit } from 'simple-git';
+
+// throws
+await simpleGit()
+   .raw('push', '--receive-pack=git-receive-pack-custom');
+
+// allows calling clone with a helper transport
+await simpleGit({ unsafe: { allowUnsafePack: true } })
+   .raw('push', '--receive-pack=git-receive-pack-custom');
+```
+
 ### Overriding allowed protocols
 
 A standard installation of `git` permits `file`, `http` and `ssh` protocols for a remote. A range of 

examples/git-output-handler.md

@@ -0,0 +1,49 @@
+## Output Handler
+
+As `simple-git` receives data on either `stdout` or `stderr` streams from the `git`
+child processes it spawns, the data is buffered for parsing when the process has
+completed.
+
+Add an `outputHandler` to the instance to pipe these streams to another target, for
+example piping to the main process `stdout` / `stderr`:
+
+```typescript
+import { InitResult, SimpleGit, simpleGit } from "simple-git";
+
+const git: SimpleGit = simpleGit()
+   .outputHandler((_command, stdout, stderr) => {
+      stdout.pipe(process.stdout);
+      stderr.pipe(process.stderr);
+   });
+
+const init: InitResult = await git.init();
+```
+
+Note: there is a single `outputHandler` per `simple-git` instance, calling the method again
+will overwrite the existing `outputHandler`.
+
+Other uses for the `outputHandler` can include tracking the processes for metrics purposes,
+such as checking how many commands are currently being executed:
+
+```typescript
+let processes = new Set();
+const currentlyRunning = () => processes.size;
+const git = context.git.outputHandler((_command, stdout, stderr) => {
+   const start = new Date();
+   const onClose = () => processes.delete(start);
+
+   stdout.on('close', onClose);
+   stderr.on('close', onClose);
+
+   processes.add(start);
+});
+
+expect(currentlyRunning()).toBe(0);
+const queue = [git.init(), git.add('*.txt')];
+
+await wait(0);
+expect(currentlyRunning()).toBe(2);
+
+await Promise.all(queue);
+expect(currentlyRunning()).toBe(0);
+```

packages/test-utils/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @simple-git/test-utils
 
+## 4.0.0
+
+### Patch Changes
+
+-  Updated dependencies [ec97a39]
+-  Updated dependencies [97fde2c]
+-  Updated dependencies [0a623e5]
+   -  [email protected]
+
 ## 3.0.0
 
 ### Patch Changes

packages/test-utils/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simple-git/test-utils",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "private": true,
   "peerDependencies": {
-    "simple-git": "^3.15.0"
+    "simple-git": "^3.19.1"
   }
 }

packages/test-utils/src/expectations.ts

@@ -17,7 +17,12 @@ export function assertGitError(
    errorConstructor: any = GitError
 ) {
    expect(errorInstance).toBeInstanceOf(errorConstructor);
-   expect(errorInstance).toHaveProperty('message', expect.stringMatching(message));
+   expect(errorInstance).toHaveProperty(
+      'message',
+      typeof message === 'string'
+         ? expect.stringContaining(message)
+         : expect.stringMatching(message)
+   );
 }
 
 export function assertGitResponseError(errorInstance: Error | unknown, git: any, equality?: any) {

simple-git/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Change History & Release Notes
 
+## 3.19.1
+
+### Patch Changes
+
+-  2ab1936: keep path splitter without path specs
+
+## 3.19.0
+
+### Minor Changes
+
+-  f702b61: Create a utility to append pathspec / file lists to tasks through the TaskOptions array/object
+
+## 3.18.0
+
+### Minor Changes
+
+-  5100f04: Add new interface for showBuffer to allow using `git show` on binary files.
+
+### Patch Changes
+
+-  f54cd0d: Examples and documentation for outputHandler
+
+## 3.17.0
+
+### Minor Changes
+
+-  a63cfc2: Timeout plugin can now be configured to ignore data on either stdOut or stdErr in the git process when determining whether to kill the spawned process.
+
+## 3.16.1
+
+### Patch Changes
+
+-  066b228: Fix overly permissive regex in push parser
+
+## 3.16.0
+
+### Minor Changes
+
+-  97fde2c: Support the use of `-B` in place of the default `-b` in checkout methods
+-  0a623e5: Adds vulnerability detection to prevent use of `--upload-pack` and `--receive-pack` without explicitly opting in.
+
+### Patch Changes
+
+-  ec97a39: Include restricting the use of git push --exec with other allowUnsafePack exclusions, thanks to @stsewd for the suggestion.
+
 ## 3.15.1
 
 ### Patch Changes

simple-git/package.json

@@ -1,7 +1,7 @@
 {
   "name": "simple-git",
   "description": "Simple GIT interface for node.js",
-  "version": "3.15.1",
+  "version": "3.19.1",
   "author": "Steve King <[email protected]>",
   "contributors": [
     {
@@ -21,7 +21,6 @@
   "devDependencies": {
     "@kwsites/promise-result": "^1.1.0",
     "@simple-git/babel-config": "^1.0.0",
-    "@simple-git/test-utils": "^3.0.0",
     "@types/debug": "^4.1.5",
     "@types/jest": "^29.2.2",
     "@types/node": "^16",