Skip to main content
The branch operations module provides a comprehensive set of functions for managing Git branches. These functions are promise-based and handle branch creation, deletion, listing, and configuration.

​
Available Functions

​
Core Branch Function

branch

Multi-purpose function for listing, creating, renaming, copying, or deleting branches using raw Git flags

​
Create and Delete Operations

createBranch

Create a new branch with existence validation

deleteBranch

Delete a branch with optional force flag

copyBranch

Copy an existing branch to a new name

​
List and Check Operations

listBranches

List all local branches

listAllBranches

List all branches (local and remote) with format options

listRemoteBranches

List remote-tracking branches

branchExists

Check if a local branch exists

currentBranch

Get the name of the current branch

getDefaultBranch

Get the repository’s default branch

​
Management Operations

renameBranch

Rename an existing branch

setBranchUpstream

Set the upstream tracking branch

resetBranchToHead

Reset a branch to HEAD

​
Common Use Cases

​
Creating a Feature Branch

import { createBranch, setBranchUpstream } from 'usegit';

// Create and configure a feature branch
await createBranch('feature/user-auth');
await setBranchUpstream('feature/user-auth', 'origin/feature/user-auth');

​
Checking Branch Existence

import { branchExists, createBranch } from 'usegit';

if (await branchExists('feature/login')) {
  console.log('Branch already exists');
} else {
  await createBranch('feature/login');
}

​
Listing Branches

import { listAllBranches } from 'usegit';

// Get structured branch data
const branches = await listAllBranches('json');
console.log('Local branches:', branches.local);
console.log('Remote branches:', branches.remote);
console.log('Default branch:', branches.head);

​
Type Definitions

​
BranchOptions

Options for the branch function: 
interface BranchOptions {
  flags?: (
    | "--all"
    | "--show-current"
    | "--list"
    | "--remotes"
    | "--force"
    | "--delete"
    | "-D"
    | "--move"
    | "-M"
    | "--copy"
    | "-C"
    | "--ignore-case"
    | "--omit-empty"
    | "--no-column"
    | "--quiet"
    | "--no-abbrev"
    | "--unset-upstream"
  )[];
  "--color"?: "always" | "auto" | "never";
  "--column"?: string;
  "--sort"?: string;
  "--abbrev"?: string;
  "--set-upstream-to"?: string;
}

​
BranchListFormat

Format options for listAllBranches: 
type BranchListFormat = "flat" | "json" | "csv";

​
BranchListResult

Return type for listAllBranches varies based on format: 
type BranchListResult<T extends BranchListFormat> = 
  T extends "flat" ? string[] :
  T extends "json" ? {
    local: string[];
    remote: string[];
    head?: string;
  } :
  T extends "csv" ? string : never;

Build docs developers (and LLMs) love

Get started for freeTalk to us