Skip to main content

​
branch

Multi-purpose function for listing, creating, renaming, copying, or deleting branches. This is a low-level function that provides direct access to Git branch operations using flags.
For most use cases, prefer the specialized functions like createBranch, deleteBranch, or copyBranch which provide better error handling and convenience.

​
Signature

function branch(): Promise<string>
function branch(opts: BranchOptions): Promise<string>
function branch(name: string, opts?: BranchOptions): Promise<string>
function branch(names: [string, string], opts?: BranchOptions): Promise<string>
Source: /home/daytona/workspace/source/src/lib/branch/branch.ts:27-33

​
Parameters

​
name
string
Branch name for single-branch operations (create, delete)
​
names
[string, string]
Source and target branch names for two-branch operations (rename, copy)
​
opts
BranchOptions
Options for the branch operation

​
Returns

​
result
Promise<string>
The output from the Git branch command

​
Examples

import { branch } from 'usegit';

// List local branches
const branches = await branch();

// List all branches (including remote)
const allBranches = await branch({ flags: ["--all"] });

// Create a new branch
await branch("feature/login");

// Delete a branch
await branch("feature/login", { flags: ["--delete"] });

// Rename a branch
await branch(["old-name", "new-name"], { flags: ["--move"] });

// Copy a branch
await branch(["main", "backup-main"], { flags: ["--copy"] });

​
createBranch

Create a new branch with automatic existence validation. Throws an error if the branch already exists.

​
Signature

function createBranch(
  name: string,
  opts?: BranchOptions
): Promise<string>
Source: /home/daytona/workspace/source/src/lib/branch/createBranch.ts:15-18

​
Parameters

​
name
string
required
The name of the branch to create
​
opts
BranchOptions
Options to pass to the underlying branch function. See branch options above.

​
Returns

​
result
Promise<string>
Success message from Git

​
Errors

​
Error
Error
Throws if the branch already exists with message: Cannot create branch "[name]": branch already exists. Use a different name or delete the existing branch first.

​
Examples

import { createBranch } from 'usegit';

// Create a simple branch
await createBranch('feature/login');

// Create a branch with custom options
await createBranch('feature/payment', {
  '--set-upstream-to': 'origin/main'
});

// Handle branch creation errors
try {
  await createBranch('existing-branch');
} catch (error) {
  console.error('Branch creation failed:', error.message);
  // Error: Cannot create branch "existing-branch": branch already exists.
}

​
deleteBranch

Delete a branch. Supports force deletion for branches with unmerged changes.

​
Signature

function deleteBranch(
  name: string,
  opts?: { force?: boolean }
): Promise<string>
Source: /home/daytona/workspace/source/src/lib/branch/deleteBranch.ts:17-27

​
Parameters

​
name
string
required
The name of the branch to delete
​
opts
object

​
Returns

​
result
Promise<string>
Success message from Git showing the deleted branch

​
Examples

import { deleteBranch } from 'usegit';

// Delete a fully merged branch
await deleteBranch('feature/login');

// Force delete a branch with unmerged changes
await deleteBranch('feature/incomplete', { force: true });

// Clean up multiple feature branches
const oldBranches = ['feature/old-1', 'feature/old-2', 'feature/old-3'];

for (const branch of oldBranches) {
  await deleteBranch(branch);
}

​
copyBranch

Copy an existing branch to a new branch name. The source branch remains unchanged.

​
Signature

function copyBranch(
  source: string,
  target: string,
  opts?: { force?: boolean }
): Promise<string>
Source: /home/daytona/workspace/source/src/lib/branch/copyBranch.ts:17-28

​
Parameters

​
source
string
required
The name of the branch to copy from
​
target
string
required
The name of the new branch to create
​
opts
object

​
Returns

​
result
Promise<string>
Success message from Git

​
Examples

import { copyBranch } from 'usegit';

// Create a backup of the main branch
await copyBranch('main', 'backup-main');

// Force copy to overwrite existing target branch
await copyBranch('main', 'backup-main', { force: true });

// Create a branch copy for experimentation
await copyBranch('feature/stable', 'feature/experiment');

// Work on the experimental branch without affecting the stable one
Copying a branch does not change your current working branch. Use Git checkout functions to switch to the newly copied branch if needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us