fix: add types and tests for the documented .exec api

readme.md

@@ -753,7 +753,7 @@ require('simple-git')()
    .push(['-u', 'origin', 'master'], () => console.log('done'));
 ```
 
-### Piping to the console for long running tasks
+### Piping to the console for long-running tasks
 
 ```js
 require('simple-git')()
@@ -773,14 +773,24 @@ require('simple-git')()
 ### Update repo and print messages when there are changes, restart the app
 
 ```javascript
+// when using a chain
 require('simple-git')()
    .exec(() => console.log('Starting pull...'))
    .pull((err, update) => {
      if(update && update.summary.changes) {
         require('child_process').exec('npm restart');
      }
    })
-  .exec(() => console.log('pull done.'));
+   .exec(() => console.log('pull done.'));
+
+// when using async and optional chaining
+const git = require('simple-git')()
+console.log('Starting pull...')
+if ((await git.pull())?.summary.changes) {
+   require('child_process').exec('npm restart');
+}
+console.log('pull done.');
+
 ```
 
 ### Get a full commits list, and then only between 0.11.0 and 0.12.0 tags

src/git.js

@@ -730,10 +730,6 @@ Git.prototype.clean = function (mode, options, then) {
    );
 };
 
-/**
- * Call a simple function at the next step in the chain.
- * @param {Function} [then]
- */
 Git.prototype.exec = function (then) {
    const task = {
       commands: [],

test/integration/exec.spec.ts

@@ -0,0 +1,23 @@
+import { createTestContext, newSimpleGit, SimpleGitTestContext } from '../__fixtures__';
+
+describe('exec', () => {
+   let context: SimpleGitTestContext;
+
+   beforeEach(async () => {
+      context = await createTestContext();
+   });
+
+   it('will exec a function between other chained methods', async () => {
+      const calls: string[] = [];
+
+      await (
+         newSimpleGit(context.root)
+         .exec(() => calls.push('a'))
+         .raw('init', () => calls.push('b'))
+         .exec(() => calls.push('c'))
+         .raw('init', () => calls.push('d'))
+      );
+
+      expect(calls).toEqual(['a', 'b', 'c', 'd']);
+   });
+})

typings/simple-git.d.ts

@@ -317,6 +317,12 @@ export interface SimpleGit extends SimpleGitBase {
 
    env(env: object): this;
 
+   /**
+    * Calls the supplied `handle` function at the next step in the chain, used to run arbitrary functions synchronously
+    * before the next task in the git api.
+    */
+   exec(handle: () => void): Response<void>;
+
    /**
     * Updates the local working copy database with changes from the default remote repo and branch.
     */