Manage Branches

function renameBranch(
  from: string,
  to: string,
  opts?: { force?: boolean }
): Promise<string>

import { renameBranch } from 'usegit';

// Rename a branch
await renameBranch('old-name', 'new-name');

// Force rename to overwrite existing branch
await renameBranch('old-name', 'existing-name', { force: true });

// Handle rename errors
try {
  await renameBranch('feature/v1', 'feature/v2');
  console.log('Branch renamed successfully');
} catch (error) {
  console.error('Rename failed:', error.message);
  // Error: Cannot rename branch "feature/v1" to "feature/v2": 
  // a branch named "feature/v2" already exists.
}

// Rename with validation
import { renameBranch, branchExists } from 'usegit';

const oldName = 'feature/old-api';
const newName = 'feature/new-api';

if (await branchExists(newName)) {
  console.log('Target branch already exists. Use force option to overwrite.');
} else {
  await renameBranch(oldName, newName);
}

function setBranchUpstream(
  branchName: string,
  upstream: string
): Promise<string>

import { setBranchUpstream } from 'usegit';

// Set upstream for a feature branch
await setBranchUpstream('feature/login', 'origin/feature/login');

// Set up a local branch to track a remote branch
await setBranchUpstream('develop', 'origin/develop');

// Now git push/pull will use origin/develop by default

// Set upstream to a different remote
await setBranchUpstream('main', 'upstream/main');

// Track from upstream instead of origin

// Create and configure a new branch
import { createBranch, setBranchUpstream } from 'usegit';

const branchName = 'feature/user-profile';
await createBranch(branchName);
await setBranchUpstream(branchName, `origin/${branchName}`);

console.log(`Branch ${branchName} is now tracking origin/${branchName}`);

function resetBranchToHead(name: string): Promise<string>

import { resetBranchToHead } from 'usegit';

// Reset a branch to current HEAD
await resetBranchToHead('feature/login');

// Move a branch pointer to match current position
// Useful when you want to update a branch reference
await resetBranchToHead('release/v1.0');

console.log('Branch pointer updated to current HEAD');

// Common workflow: update a branch to match current work
import { resetBranchToHead, currentBranch } from 'usegit';

const current = await currentBranch();
console.log(`Current branch: ${current}`);

// Reset another branch to point to the same commit
await resetBranchToHead('backup-branch');

console.log('backup-branch now points to the same commit');

import { createBranch, setBranchUpstream, currentBranch } from 'usegit';

const featureName = 'feature/payment-integration';

// Create the branch
await createBranch(featureName);

// Switch to it (using git checkout - not shown)
// ...

// Set up upstream tracking
await setBranchUpstream(featureName, `origin/${featureName}`);

const current = await currentBranch();
console.log(`Now on ${current} with upstream configured`);

import { renameBranch, branchExists } from 'usegit';

async function safeBranchRename(oldName: string, newName: string) {
  // Check if target name is available
  if (await branchExists(newName)) {
    throw new Error(`Branch ${newName} already exists`);
  }
  
  // Perform the rename
  await renameBranch(oldName, newName);
  console.log(`Successfully renamed ${oldName} to ${newName}`);
}

await safeBranchRename('feature/old-name', 'feature/new-name');

import { copyBranch, resetBranchToHead } from 'usegit';

// Create a backup before making changes
await copyBranch('main', 'main-backup');

// ... make changes ...

// If needed, restore from backup
await resetBranchToHead('main-backup');