feat(branch): add force param to overwrite existing branch

Author: alex-titarenko

package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-essentials",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "description": "The essential GIT commands",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/api/branch.ts

@@ -20,6 +20,9 @@ type BranchParams = {
 
   /** Update `HEAD` to point at the newly created branch. */
   checkout?: boolean
+
+  /** Instead of throwing an error if a branched named `ref` already exists, overwrite the existing branch. */
+  force?: boolean
 }
 
 /**
@@ -40,6 +43,7 @@ export async function branch({
   gitdir = join(dir, '.git'),
   ref,
   checkout = false,
+  force = false,
 }: BranchParams): Promise<void> {
   try {
     assertParameter('fs', fs)
@@ -50,6 +54,7 @@ export async function branch({
       gitdir,
       ref,
       checkout,
+      force
     })
   } catch (err: any) {
     err.caller = 'git.branch'

src/commands/branch.ts

@@ -10,6 +10,7 @@ type BranchParams = {
   gitdir: string
   ref: string
   checkout?: boolean
+  force?: boolean
 }
 
 /**
@@ -24,16 +25,19 @@ type BranchParams = {
  * console.log('done')
  *
  */
-export async function _branch({ fs, gitdir, ref, checkout = false }: BranchParams): Promise<void> {
+export async function _branch(
+  { fs, gitdir, ref, checkout = false, force = false }: BranchParams): Promise<void> {
   if (ref !== cleanGitRef.clean(ref)) {
     throw new InvalidRefNameError(ref, cleanGitRef.clean(ref))
   }
 
   const fullref = `refs/heads/${ref}`
 
-  const exist = await GitRefManager.exists({ fs, gitdir, ref: fullref })
-  if (exist) {
-    throw new AlreadyExistsError('branch', ref, false)
+  if (!force) {
+    const exist = await GitRefManager.exists({ fs, gitdir, ref: fullref })
+    if (exist) {
+      throw new AlreadyExistsError('branch', ref, false)
+    }
   }
 
   // Get current HEAD tree oid

tests/branch.test.ts

@@ -1,6 +1,6 @@
-import { Errors, branch, init, currentBranch } from '../src'
+import { Errors, branch, init, currentBranch, listFiles } from '../src'
 import { makeFsFixture, FsFixtureData } from './helpers/makeFsFixture'
-import { expectToFailWithTypeAsync } from './helpers/assertionHelper'
+import { expectNotToFailAsync, expectToFailWithTypeAsync } from './helpers/assertionHelper'
 import * as path from './helpers/path'
 
 import branchFsFixtureData from './fixtures/fs/branch.json'
@@ -19,6 +19,89 @@ describe('branch', () => {
     expect(await currentBranch({ fs, dir })).toBe('main')
   })
 
+  it('branch force=false', async () => {
+    // arrange
+    const { fs, dir } = await makeFsFixture(branchFsFixtureData as FsFixtureData)
+
+    // act
+    await branch({ fs, dir, ref: 'test-branch' })
+
+    // assert
+    expect(await currentBranch({ fs, dir })).toEqual('main')
+    expect(await fs.exists(path.resolve(dir, '.git', 'refs/heads/test-branch'))).toBeTruthy()
+
+    // act
+    const action = async () => {
+      await branch({ fs, dir, ref: 'test-branch' })
+    }
+
+    // assert
+    await expectToFailWithTypeAsync(action, Errors.AlreadyExistsError)
+  })
+
+  it('branch force=false', async () => {
+    // arrange
+    const { fs, dir } = await makeFsFixture(branchFsFixtureData as FsFixtureData)
+
+    // act
+    await branch({ fs, dir, ref: 'test-branch' })
+
+    // assert
+    expect(await currentBranch({ fs, dir })).toEqual('main')
+    expect(await fs.exists(path.resolve(dir, '.git', 'refs/heads/test-branch'))).toBeTruthy()
+
+    // act
+    const action = async () => {
+      await branch({ fs, dir, ref: 'test-branch', force: false })
+    }
+
+    // assert
+    await expectToFailWithTypeAsync(action, Errors.AlreadyExistsError)
+  })
+
+  it('branch force=true', async () => {
+    // arrange
+    const { fs, dir } = await makeFsFixture(branchFsFixtureData as FsFixtureData)
+
+    // act
+    await branch({ fs, dir, ref: 'test-branch' })
+
+    // assert
+    expect(await currentBranch({ fs, dir })).toEqual('main')
+    expect(await fs.exists(path.resolve(dir, '.git', 'refs/heads/test-branch'))).toBeTruthy()
+
+    // act
+    const action = async () => {
+      await branch({ fs, dir, ref: 'test-branch', force: true })
+    }
+
+    // assert
+    await expectNotToFailAsync(action)
+  })
+
+  // it('branch with start point force', async () => {
+  //   // arrange
+  //   const { fs, dir } = await makeFsFixture('test-branch-start-point')
+
+  //   // act
+  //   await branch({ fs, dir, ref: 'test-branch', startPoint: 'start-point' })
+
+  //   // assert
+  //   expect(await currentBranch({ fs, dir })).toEqual('main')
+  //   expect(await fs.exists(path.resolve(dir, '.git', 'refs/heads/test-branch'))).toBeTruthy()
+
+  //   // act
+  //   const action = async () => {
+  //     await branch({ fs, dir, ref: 'test-branch', force: true })
+  //   }
+
+  //   // assert
+  //   await expectNotToFailAsync(action)
+  //   expect(await listFiles({ fs, dir, ref: 'test-branch' })).toEqual([
+  //     'new-file.txt',
+  //   ])
+  // })
+
   it('branch --checkout', async () => {
     // arrange
     const { fs, dir } = await makeFsFixture(branchFsFixtureData as FsFixtureData)

tests/helpers/assertionHelper.ts

@@ -39,3 +39,14 @@ export async function expectToFailWithErrorAsync(action: () => Promise<void>, er
   expect(error).toEqual(err)
 }
 
+export async function expectNotToFailAsync(action: () => Promise<void>) {
+  let error: any
+
+  try {
+    await action()
+  } catch (e: any) {
+    error = e
+  }
+
+  expect(error).toBeUndefined()
+}