Add support for using the -B modifier instead of the default -b w…

…hen using `checkoutBranch` / `checkoutLocalBranch`.

Based on requirement detailed in #873

.changeset/nasty-bikes-dance.md

@@ -0,0 +1,5 @@
+---
+'simple-git': minor
+---
+
+Support the use of `-B` in place of the default `-b` in checkout methods

simple-git/src/git.js

@@ -25,7 +25,6 @@ const { checkIgnoreTask } = require('./lib/tasks/check-ignore');
 const { checkIsRepoTask } = require('./lib/tasks/check-is-repo');
 const { cloneTask, cloneMirrorTask } = require('./lib/tasks/clone');
 const { cleanWithOptionsTask, isCleanOptionsArray } = require('./lib/tasks/clean');
-const { commitTask } = require('./lib/tasks/commit');
 const { diffSummaryTask } = require('./lib/tasks/diff');
 const { fetchTask } = require('./lib/tasks/fetch');
 const { moveTask } = require('./lib/tasks/move');
@@ -283,33 +282,6 @@ Git.prototype.addAnnotatedTag = function (tagName, tagMessage) {
    );
 };
 
-/**
- * Check out a tag or revision, any number of additional arguments can be passed to the `git checkout` command
- * by supplying either a string or array of strings as the first argument.
- */
-Git.prototype.checkout = function () {
-   const commands = ['checkout', ...getTrailingOptions(arguments, true)];
-   return this._runTask(straightThroughStringTask(commands), trailingFunctionArgument(arguments));
-};
-
-/**
- * Check out a remote branch
- *
- * @param {string} branchName name of branch
- * @param {string} startPoint (e.g origin/development)
- * @param {Function} [then]
- */
-Git.prototype.checkoutBranch = function (branchName, startPoint, then) {
-   return this.checkout(['-b', branchName, startPoint], trailingFunctionArgument(arguments));
-};
-
-/**
- * Check out a local branch
- */
-Git.prototype.checkoutLocalBranch = function (branchName, then) {
-   return this.checkout(['-b', branchName], trailingFunctionArgument(arguments));
-};
-
 /**
  * Delete a local branch
  */

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

@@ -1,6 +1,7 @@
 import { SimpleGitBase } from '../../typings';
 import { taskCallback } from './task-callback';
 import { changeWorkingDirectoryTask } from './tasks/change-working-directory';
+import checkout from './tasks/checkout';
 import commit from './tasks/commit';
 import config from './tasks/config';
 import grep from './tasks/grep';
@@ -137,4 +138,4 @@ export class SimpleGitApi implements SimpleGitBase {
    }
 }
 
-Object.assign(SimpleGitApi.prototype, commit(), config(), grep(), log(), version());
+Object.assign(SimpleGitApi.prototype, checkout(), commit(), config(), grep(), log(), version());

simple-git/src/lib/tasks/checkout.ts

@@ -0,0 +1,38 @@
+import type { SimpleGit } from '../../../typings';
+import type { SimpleGitApi } from '../simple-git-api';
+import { getTrailingOptions, remove, trailingFunctionArgument } from '../utils';
+import { straightThroughStringTask } from './task';
+
+function checkoutTask(args: string[]) {
+   const commands = ['checkout', ...args];
+   if (commands[1] === '-b' && commands.includes('-B')) {
+      commands[1] = remove(commands, '-B');
+   }
+
+   return straightThroughStringTask(commands);
+}
+
+export default function (): Pick<SimpleGit, 'checkout' | 'checkoutBranch' | 'checkoutLocalBranch'> {
+   return {
+      checkout(this: SimpleGitApi) {
+         return this._runTask(
+            checkoutTask(getTrailingOptions(arguments, 1)),
+            trailingFunctionArgument(arguments)
+         );
+      },
+
+      checkoutBranch(this: SimpleGitApi, branchName, startPoint) {
+         return this._runTask(
+            checkoutTask(['-b', branchName, startPoint, ...getTrailingOptions(arguments)]),
+            trailingFunctionArgument(arguments)
+         );
+      },
+
+      checkoutLocalBranch(this: SimpleGitApi, branchName) {
+         return this._runTask(
+            checkoutTask(['-b', branchName, ...getTrailingOptions(arguments)]),
+            trailingFunctionArgument(arguments)
+         );
+      },
+   };
+}

simple-git/test/unit/checkout.spec.ts

@@ -57,6 +57,13 @@ describe('checkout', () => {
    });
 
    describe('checkoutLocalBranch', () => {
+      it('allows using -B', async () => {
+         git.checkoutLocalBranch('foo', { '-B': null });
+         await closeWithSuccess();
+
+         assertExecutedCommands('checkout', '-B', 'foo');
+      });
+
       it('with callback', async () => {
          git.checkoutLocalBranch('new-branch', callback);
          await closeWithSuccess();
@@ -76,6 +83,13 @@ describe('checkout', () => {
    });
 
    describe('checkoutBranch', () => {
+      it('allows using -B', async () => {
+         git.checkoutBranch('foo', 'bar', ['-B']);
+         await closeWithSuccess();
+
+         assertExecutedCommands('checkout', '-B', 'foo', 'bar');
+      });
+
       it('with callback', async function () {
          git.checkoutBranch('branch', 'start', callback);
 

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

@@ -319,7 +319,7 @@ export interface SimpleGit extends SimpleGitBase {
    ): Response<string>;
 
    /**
-    * Checkout a remote branch.
+    * Checkout a remote branch - equivalent to `git checkout -b ${branchName} ${startPoint}`
     *
     * - branchName name of branch.
     * - startPoint (e.g origin/development).
@@ -330,6 +330,13 @@ export interface SimpleGit extends SimpleGitBase {
       callback?: types.SimpleGitTaskCallback<void>
    ): Response<void>;
 
+   checkoutBranch(
+      branchName: string,
+      startPoint: string,
+      options?: types.TaskOptions,
+      callback?: types.SimpleGitTaskCallback<void>
+   ): Response<void>;
+
    /**
     * Internally uses pull and tags to get the list of tags then checks out the latest tag.
     */
@@ -340,13 +347,19 @@ export interface SimpleGit extends SimpleGitBase {
    ): Response<void>;
 
    /**
-    * Checkout a local branch
+    * Checkout a local branch - equivalent to `git checkout -b ${branchName}`
     */
    checkoutLocalBranch(
       branchName: string,
       callback?: types.SimpleGitTaskCallback<void>
    ): Response<void>;
 
+   checkoutLocalBranch(
+      branchName: string,
+      options?: types.TaskOptions,
+      callback?: types.SimpleGitTaskCallback<void>
+   ): Response<void>;
+
    /**
     * Deletes unwanted content from the local repo - when supplying the first argument as
     * an array of `CleanOptions`, the array must include one of `CleanOptions.FORCE` or