Add callback support to git.firstCommit (#960)

* Add callback support to `git.firstCommit`

.changeset/all-humans-wash.md

@@ -0,0 +1,5 @@
+---
+'simple-git': patch
+---
+
+Add trailing callback support to git.firstCommit

simple-git/readme.md

@@ -308,6 +308,8 @@ in v2 (deprecation notices were logged to `stdout` as `console.warn` in v2).
    -  `options.strictDate` - switches the authored date value from an ISO 8601-like format to be strict ISO 8601 format
    -  `options.symmetric` - defaults to true, enables [symmetric revision range](https://git-scm.com/docs/gitrevisions#_dotted_range_notations) rather than a two-dot range
    -  `options.to` - sets the newset commit in the range to return, use along with `options.from` to set a bounded range
+
+   When only one of `options.from` and `options.to` is supplied, the default value of the omitted option is equivalent to `HEAD`. For any other commit, explicitly supply both from and to commits (for example use `await git.firstCommit()` as the default value of `from` to log since the first commit of the repo). 
 
 ## git merge
 

simple-git/src/lib/tasks/first-commit.ts

@@ -1,16 +1,15 @@
 import { Response, SimpleGit } from '../../../typings';
 import { SimpleGitApi } from '../simple-git-api';
+import { trailingFunctionArgument } from '../utils';
+import { straightThroughStringTask } from './task';
 
 export default function (): Pick<SimpleGit, 'firstCommit'> {
    return {
       firstCommit(this: SimpleGitApi): Response<string> {
-         return this._runTask({
-            commands: ['rev-list', '--max-parents=0', 'HEAD'],
-            format: 'utf-8',
-            parser(stdOut) {
-               return String(stdOut).trim();
-            },
-         });
+         return this._runTask(
+            straightThroughStringTask(['rev-list', '--max-parents=0', 'HEAD'], true),
+            trailingFunctionArgument(arguments)
+         );
       },
    };
 }

simple-git/test/unit/first-commit.spec.ts

@@ -1,11 +1,20 @@
 import { assertExecutedCommands, closeWithSuccess, newSimpleGit } from './__fixtures__';
 
 describe('firstCommit', () => {
-   it('gets the first commit in a repo', async () => {
+   it('gets the first commit in a repo async', async () => {
       const task = newSimpleGit().firstCommit();
       await closeWithSuccess('a-commit-hash\n');
 
       expect(await task).toBe('a-commit-hash');
       assertExecutedCommands('rev-list', '--max-parents=0', 'HEAD');
    });
+
+   it('gets the first commit in a repo callback', async () => {
+      const callback = jest.fn();
+      const task = newSimpleGit().firstCommit(callback);
+      await closeWithSuccess('a-commit-hash\n');
+
+      expect(callback).toHaveBeenCalledWith(null, await task);
+      assertExecutedCommands('rev-list', '--max-parents=0', 'HEAD');
+   });
 });

simple-git/typings/simple-git.d.ts

@@ -566,7 +566,7 @@ export interface SimpleGit extends SimpleGitBase {
    /**
     * Gets the commit hash of the first commit in the repo
     */
-   firstCommit(): Response<string>;
+   firstCommit(callback?: types.SimpleGitTaskCallback<string>): Response<string>;
 
    /**
     * Gets the current value of a configuration property by it key, optionally specify the scope in which