0
# Branch Management
1

2
Creating, switching, listing, and managing branches.
3

4
## Capabilities
5

6
### Create Branch
7

8
Creates a new branch pointing to a specific commit.
9

10
```javascript { .api }
11
/**
12
 * Create a new branch
13
 * @param args.fs - File system client
14
 * @param args.dir - Working tree directory path
15
 * @param args.gitdir - Git directory path
16
 * @param args.ref - Branch name to create
17
 * @param args.object - Commit SHA to point branch at (defaults to HEAD)
18
 * @param args.checkout - Whether to checkout the new branch
19
 * @param args.force - Overwrite existing branch
20
 * @returns Promise resolving when branch is created
21
 */
22
function branch(args: {
23
  fs: FsClient;
24
  dir?: string;
25
  gitdir?: string;
26
  ref: string;
27
  object?: string;
28
  checkout?: boolean;
29
  force?: boolean;
30
}): Promise<void>;
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
import git from "isomorphic-git";  
37
import fs from "fs";
38

39
// Create a new branch from current HEAD
40
await git.branch({
41
  fs,
42
  dir: "/path/to/repo",
43
  ref: "feature-branch"
44
});
45

46
// Create and checkout new branch
47
await git.branch({
48
  fs,
49
  dir: "/path/to/repo", 
50
  ref: "feature-branch",
51
  checkout: true
52
});
53

54
// Create branch from specific commit
55
await git.branch({
56
  fs,
57
  dir: "/path/to/repo",
58
  ref: "hotfix-branch",
59
  object: "abc123..."
60
});
61

62
// Force create branch (overwrite existing)
63
await git.branch({
64
  fs,
65
  dir: "/path/to/repo",
66
  ref: "existing-branch",
67
  force: true
68
});
69
```
70

71
### Checkout Branch or Files
72

73
Switches to a different branch or checks out specific files.
74

75
```javascript { .api }
76
/**
77
 * Checkout a branch or specific files
78
 * @param args.fs - File system client
79
 * @param args.dir - Working tree directory path
80
 * @param args.gitdir - Git directory path
81
 * @param args.ref - Branch name or commit to checkout
82
 * @param args.remote - Remote name for tracking branches
83
 * @param args.noCheckout - Don't update working directory
84
 * @param args.force - Overwrite local changes
85
 * @param args.track - Set up tracking relationship
86
 * @param args.filepaths - Specific files to checkout
87
 * @param args.cache - Cache object
88
 * @param args.onProgress - Progress callback
89
 * @returns Promise resolving when checkout completes
90
 */
91
function checkout(args: {
92
  fs: FsClient;
93
  dir?: string;
94
  gitdir?: string;
95
  ref: string;
96
  remote?: string;
97
  noCheckout?: boolean;
98
  force?: boolean;
99
  track?: boolean;
100
  filepaths?: string[];
101
  cache?: object;
102
  onProgress?: ProgressCallback;
103
}): Promise<void>;
104
```
105

106
**Usage Examples:**
107

108
```javascript
109
import git from "isomorphic-git";
110
import fs from "fs";
111

112
// Checkout existing branch
113
await git.checkout({
114
  fs,
115
  dir: "/path/to/repo",
116
  ref: "feature-branch"
117
});
118

119
// Checkout remote branch and set up tracking
120
await git.checkout({
121
  fs,
122
  dir: "/path/to/repo",
123
  ref: "feature-branch",
124
  remote: "origin",
125
  track: true
126
});
127

128
// Checkout specific commit (detached HEAD)
129
await git.checkout({
130
  fs,
131
  dir: "/path/to/repo",
132
  ref: "abc123..."
133
});
134

135
// Checkout specific files from another branch
136
await git.checkout({
137
  fs,
138
  dir: "/path/to/repo",
139
  ref: "main",
140
  filepaths: ["src/config.js", "README.md"]
141
});
142

143
// Force checkout (discard local changes)
144
await git.checkout({
145
  fs,
146
  dir: "/path/to/repo",
147
  ref: "main",
148
  force: true
149
});
150
```
151

152
### Get Current Branch
153

154
Returns the name of the currently checked out branch.
155

156
```javascript { .api }
157
/**
158
 * Get the current branch name
159
 * @param args.fs - File system client
160
 * @param args.dir - Working tree directory path
161
 * @param args.gitdir - Git directory path
162
 * @param args.fullname - Return full reference name
163
 * @returns Promise resolving to branch name or undefined if detached HEAD
164
 */
165
function currentBranch(args: {
166
  fs: FsClient;
167
  dir?: string;
168
  gitdir?: string;
169
  fullname?: boolean;
170
}): Promise<string | undefined>;
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
import git from "isomorphic-git";
177
import fs from "fs";
178

179
// Get current branch name
180
const branch = await git.currentBranch({
181
  fs,
182
  dir: "/path/to/repo"
183
});
184
console.log("Current branch:", branch); // "main"
185

186
// Get full reference name
187
const fullRef = await git.currentBranch({
188
  fs,
189
  dir: "/path/to/repo",
190
  fullname: true
191
});
192
console.log("Full ref:", fullRef); // "refs/heads/main"
193

194
// Handle detached HEAD
195
const detachedBranch = await git.currentBranch({
196
  fs,
197
  dir: "/path/to/repo"
198
});
199
if (detachedBranch === undefined) {
200
  console.log("In detached HEAD state");
201
}
202
```
203

204
### List Branches
205

206
Lists all local or remote branches.
207

208
```javascript { .api }
209
/**
210
 * List branches
211
 * @param args.fs - File system client
212
 * @param args.dir - Working tree directory path
213
 * @param args.gitdir - Git directory path  
214
 * @param args.remote - Remote name to list remote branches
215
 * @returns Promise resolving to array of branch names
216
 */
217
function listBranches(args: {
218
  fs: FsClient;
219
  dir?: string;
220
  gitdir?: string;
221
  remote?: string;
222
}): Promise<string[]>;
223
```
224

225
**Usage Examples:**
226

227
```javascript
228
import git from "isomorphic-git";
229
import fs from "fs";
230

231
// List all local branches
232
const localBranches = await git.listBranches({
233
  fs,
234
  dir: "/path/to/repo"
235
});
236
console.log("Local branches:", localBranches);
237
// ["main", "feature-branch", "hotfix"]
238

239
// List remote branches
240
const remoteBranches = await git.listBranches({
241
  fs,
242
  dir: "/path/to/repo",
243
  remote: "origin"
244
});
245
console.log("Remote branches:", remoteBranches);
246
// ["main", "develop", "feature-1"]
247

248
// List all remotes and their branches
249
const remotes = await git.listRemotes({ fs, dir: "/path/to/repo" });
250
for (const remote of remotes) {
251
  const branches = await git.listBranches({
252
    fs,
253
    dir: "/path/to/repo",
254
    remote: remote.remote
255
  });
256
  console.log(`${remote.remote}:`, branches);
257
}
258
```
259

260
### Delete Branch
261

262
Deletes a local branch.
263

264
```javascript { .api }
265
/**
266
 * Delete a branch
267
 * @param args.fs - File system client
268
 * @param args.dir - Working tree directory path
269
 * @param args.gitdir - Git directory path
270
 * @param args.ref - Branch name to delete
271
 * @returns Promise resolving when branch is deleted
272
 */
273
function deleteBranch(args: {
274
  fs: FsClient;
275
  dir?: string;
276
  gitdir?: string;
277
  ref: string;
278
}): Promise<void>;
279
```
280

281
**Usage Example:**
282

283
```javascript
284
import git from "isomorphic-git";
285
import fs from "fs";
286

287
// Delete a branch
288
await git.deleteBranch({
289
  fs,
290
  dir: "/path/to/repo",
291
  ref: "old-feature-branch"
292
});
293
```
294

295
### Rename Branch
296

297
Renames a branch.
298

299
```javascript { .api }
300
/**
301
 * Rename a branch
302
 * @param args.fs - File system client
303
 * @param args.dir - Working tree directory path
304
 * @param args.gitdir - Git directory path
305
 * @param args.oldref - Current branch name
306
 * @param args.newref - New branch name
307
 * @param args.checkout - Whether to checkout the renamed branch
308
 * @returns Promise resolving when branch is renamed
309
 */
310
function renameBranch(args: {
311
  fs: FsClient;
312
  dir?: string;
313
  gitdir?: string;
314
  oldref: string;
315
  newref: string;
316
  checkout?: boolean;
317
}): Promise<void>;
318
```
319

320
**Usage Example:**
321

322
```javascript
323
import git from "isomorphic-git";
324
import fs from "fs";
325

326
// Rename a branch
327
await git.renameBranch({
328
  fs,
329
  dir: "/path/to/repo",
330
  oldref: "old-branch-name",
331
  newref: "new-branch-name"
332
});
333

334
// Rename current branch
335
await git.renameBranch({
336
  fs,
337
  dir: "/path/to/repo",
338
  oldref: "current-branch",
339
  newref: "renamed-branch",
340
  checkout: true
341
});
342
```
343

344
### Fast Forward Merge
345

346
Performs a fast-forward merge to move a branch pointer.
347

348
```javascript { .api }
349
/**
350
 * Fast-forward a branch
351
 * @param args.fs - File system client
352
 * @param args.dir - Working tree directory path
353
 * @param args.gitdir - Git directory path
354
 * @param args.ref - Branch to fast-forward
355
 * @param args.oid - Target commit SHA
356
 * @returns Promise resolving when fast-forward completes
357
 */
358
function fastForward(args: {
359
  fs: FsClient;
360
  dir?: string;
361
  gitdir?: string;
362
  ref: string;
363
  oid: string;
364
}): Promise<void>;
365
```
366

367
**Usage Example:**
368

369
```javascript
370
import git from "isomorphic-git";
371
import fs from "fs";
372

373
// Fast-forward current branch to latest commit from remote
374
const commits = await git.log({
375
  fs,
376
  dir: "/path/to/repo",
377
  ref: "origin/main",
378
  depth: 1
379
});
380

381
await git.fastForward({
382
  fs,
383
  dir: "/path/to/repo",
384
  ref: "main",
385
  oid: commits[0].oid
386
});
387
```
388

389
## Branch Workflow Examples
390

391
### Create Feature Branch Workflow
392

393
```javascript
394
import git from "isomorphic-git";
395
import fs from "fs";
396

397
// Start from main branch
398
await git.checkout({ fs, dir: "/path/to/repo", ref: "main" });
399

400
// Create and checkout feature branch
401
await git.branch({
402
  fs,
403
  dir: "/path/to/repo",
404
  ref: "feature/new-component",
405
  checkout: true
406
});
407

408
// Work on feature...
409
// Stage and commit changes
410
await git.add({ fs, dir: "/path/to/repo", filepath: "src/component.js" });
411
await git.commit({
412
  fs,
413
  dir: "/path/to/repo",
414
  message: "Add new component",
415
  author: { name: "Developer", email: "dev@example.com" }
416
});
417
```
418

419
### Switch Between Branches
420

421
```javascript
422
import git from "isomorphic-git";
423
import fs from "fs";
424

425
// Check current branch
426
const current = await git.currentBranch({ fs, dir: "/path/to/repo" });
427
console.log("Currently on:", current);
428

429
// Switch to different branch
430
await git.checkout({ fs, dir: "/path/to/repo", ref: "develop" });
431

432
// List all branches to see options
433
const branches = await git.listBranches({ fs, dir: "/path/to/repo" });
434
console.log("Available branches:", branches);
435
```