Create utility git.firstCommit() to fetch the commit hash of the fi… (#958)

* Create utility `git.firstCommit()` to fetch the commit hash of the first commit in the repo

Author: steveukx

.changeset/nervous-humans-wash.md

@@ -0,0 +1,5 @@
+---
+'simple-git': minor
+---
+
+Add firstCommit utility interface

simple-git/readme.md

@@ -375,6 +375,8 @@ in v2 (deprecation notices were logged to `stdout` as `console.warn` in v2).
 -  `.checkIsRepo('bare')` gets whether the current working directory is within a bare git repo (see either [git clone --bare](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---bare) or [git init --bare](https://git-scm.com/docs/git-init#Documentation/git-init.txt---bare)).
 -  `.checkIsRepo('root')` gets whether the current working directory is the root directory for a repo (sub-directories will return false).
 
+-  `.firstCommit()` gets the commit hash of the first commit made to the current repo.
+
 ## git show
 
 - `.show(options)` show various types of objects for example the file content at a certain commit. `options` is the single value string or any [options](#how-to-specify-options) supported by the [git show](https://git-scm.com/docs/git-show) command.

simple-git/src/lib/simple-git-api.ts

@@ -4,6 +4,7 @@ import { changeWorkingDirectoryTask } from './tasks/change-working-directory';
 import checkout from './tasks/checkout';
 import commit from './tasks/commit';
 import config from './tasks/config';
+import firstCommit from './tasks/first-commit';
 import grep from './tasks/grep';
 import { hashObjectTask } from './tasks/hash-object';
 import { initTask } from './tasks/init';
@@ -144,6 +145,7 @@ Object.assign(
    checkout(),
    commit(),
    config(),
+   firstCommit(),
    grep(),
    log(),
    show(),

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

@@ -0,0 +1,16 @@
+import { Response, SimpleGit } from '../../../typings';
+import { SimpleGitApi } from '../simple-git-api';
+
+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();
+            },
+         });
+      },
+   };
+}

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

@@ -0,0 +1,11 @@
+import { assertExecutedCommands, closeWithSuccess, newSimpleGit } from './__fixtures__';
+
+describe('firstCommit', () => {
+   it('gets the first commit in a repo', 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');
+   });
+});

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

@@ -563,6 +563,11 @@ export interface SimpleGit extends SimpleGitBase {
 
    fetch(callback?: types.SimpleGitTaskCallback<resp.FetchResult>): Response<resp.FetchResult>;
 
+   /**
+    * Gets the commit hash of the first commit in the repo
+    */
+   firstCommit(): Response<string>;
+
    /**
     * Gets the current value of a configuration property by it key, optionally specify the scope in which
     * to run the command (omit / set to `undefined` to check in the complete overlaid configuration visible