0
# References and Branches
1

2
Branch and reference management including creation, deletion, and traversal of Git references. References are Git's way of storing simple names for SHA-1 hashes, including branches, tags, and special references like HEAD.
3

4
## Capabilities
5

6
### Reference Operations
7

8
Core reference management and lookup operations.
9

10
```javascript { .api }
11
/**
12
 * Create a new reference
13
 * @param {Repository} repo - Repository instance
14
 * @param {string} name - Reference name (e.g., "refs/heads/feature")
15
 * @param {Oid} oid - Target object ID
16
 * @param {boolean} force - Force creation if reference exists
17
 * @param {string} logMessage - Reflog message
18
 * @returns {Promise<Reference>} New reference
19
 */
20
Reference.create(repo, name, oid, force, logMessage): Promise<Reference>;
21

22
/**
23
 * Create reference matching current value
24
 * @param {Repository} repo - Repository instance
25
 * @param {string} name - Reference name
26
 * @param {Oid} oid - New target OID
27
 * @param {boolean} force - Force creation
28
 * @param {Oid} currentId - Expected current OID
29
 * @param {string} logMessage - Reflog message
30
 * @returns {Promise<Reference>} New reference
31
 */
32
Reference.createMatching(repo, name, oid, force, currentId, logMessage): Promise<Reference>;
33

34
/**
35
 * Create symbolic reference
36
 * @param {Repository} repo - Repository instance
37
 * @param {string} name - Reference name
38
 * @param {string} target - Target reference name
39
 * @param {boolean} force - Force creation
40
 * @param {string} logMessage - Reflog message
41
 * @returns {Promise<Reference>} New symbolic reference
42
 */
43
Reference.symbolicCreate(repo, name, target, force, logMessage): Promise<Reference>;
44

45
/**
46
 * Look up reference by name
47
 * @param {Repository} repo - Repository instance
48
 * @param {string} name - Reference name
49
 * @returns {Promise<Reference>} Reference object
50
 */
51
Reference.lookup(repo, name): Promise<Reference>;
52

53
/**
54
 * Expand shorthand reference name
55
 * @param {Repository} repo - Repository instance
56
 * @param {string} shorthand - Shorthand name (e.g., "main", "origin/main")
57
 * @returns {Promise<string>} Full reference name
58
 */
59
Reference.dwim(repo, shorthand): Promise<string>;
60

61
/**
62
 * List all references
63
 * @param {Repository} repo - Repository instance
64
 * @returns {Promise<string[]>} Array of reference names
65
 */
66
Reference.list(repo): Promise<string[]>;
67

68
/**
69
 * Get OID from reference name
70
 * @param {Repository} repo - Repository instance
71
 * @param {string} name - Reference name
72
 * @returns {Promise<Oid>} Target OID
73
 */
74
Reference.nameToId(repo, name): Promise<Oid>;
75

76
/**
77
 * Remove reference
78
 * @param {Repository} repo - Repository instance
79
 * @param {string} name - Reference name to remove
80
 * @returns {Promise<void>}
81
 */
82
Reference.remove(repo, name): Promise<void>;
83
```
84

85
**Usage Examples:**
86

87
```javascript
88
const NodeGit = require('nodegit');
89

90
const repo = await NodeGit.Repository.open('./my-repo');
91
const commit = await repo.getHeadCommit();
92

93
// Create new branch reference
94
const branchRef = await NodeGit.Reference.create(
95
  repo,
96
  'refs/heads/feature-branch',
97
  commit.id(),
98
  false,
99
  'Created feature branch'
100
);
101

102
// Look up existing reference
103
const masterRef = await NodeGit.Reference.lookup(repo, 'refs/heads/main');
104
console.log('Main branch points to:', masterRef.target().tostrS());
105

106
// Expand shorthand name
107
const fullName = await NodeGit.Reference.dwim(repo, 'main');
108
console.log('Full name:', fullName); // "refs/heads/main"
109

110
// List all references
111
const allRefs = await NodeGit.Reference.list(repo);
112
allRefs.forEach(function(refName) {
113
  console.log('Reference:', refName);
114
});
115
```
116

117
### Reference Instance Methods
118

119
Methods available on Reference objects.
120

121
```javascript { .api }
122
/**
123
 * Get reference name
124
 * @returns {string} Full reference name
125
 */
126
reference.name(): string;
127

128
/**
129
 * Get shorthand reference name
130
 * @returns {string} Shorthand name (e.g., "main" instead of "refs/heads/main")
131
 */
132
reference.shorthand(): string;
133

134
/**
135
 * Get target OID (for direct references)
136
 * @returns {Oid} Target object ID
137
 */
138
reference.target(): Oid;
139

140
/**
141
 * Get symbolic target (for symbolic references)
142
 * @returns {string} Target reference name
143
 */
144
reference.symbolicTarget(): string;
145

146
/**
147
 * Get reference type
148
 * @returns {number} Reference type (OID or SYMBOLIC)
149
 */
150
reference.type(): number;
151

152
/**
153
 * Check if reference is a branch
154
 * @returns {boolean} True if branch reference
155
 */
156
reference.isBranch(): boolean;
157

158
/**
159
 * Check if reference is a remote branch
160
 * @returns {boolean} True if remote reference
161
 */
162
reference.isRemote(): boolean;
163

164
/**
165
 * Check if reference is a tag
166
 * @returns {boolean} True if tag reference
167
 */
168
reference.isTag(): boolean;
169

170
/**
171
 * Check if reference is HEAD
172
 * @returns {boolean} True if HEAD reference
173
 */
174
reference.isHead(): boolean;
175

176
/**
177
 * Check if reference is concrete (direct)
178
 * @returns {boolean} True if direct reference
179
 */
180
reference.isConcrete(): boolean;
181

182
/**
183
 * Get branch name if this is a branch reference
184
 * @returns {string} Branch name
185
 */
186
reference.branch(): string;
187

188
/**
189
 * Resolve symbolic reference to direct reference
190
 * @returns {Promise<Reference>} Direct reference
191
 */
192
reference.resolve(): Promise<Reference>;
193

194
/**
195
 * Set reference target OID
196
 * @param {Oid} oid - New target OID
197
 * @param {string} logMessage - Reflog message
198
 * @returns {Promise<Reference>} Updated reference
199
 */
200
reference.setTarget(oid, logMessage): Promise<Reference>;
201

202
/**
203
 * Set symbolic reference target
204
 * @param {string} target - New target reference name
205
 * @param {string} logMessage - Reflog message
206
 * @returns {Promise<Reference>} Updated reference
207
 */
208
reference.symbolicSetTarget(target, logMessage): Promise<Reference>;
209

210
/**
211
 * Rename reference
212
 * @param {string} newName - New reference name
213
 * @param {boolean} force - Force rename
214
 * @param {string} logMessage - Reflog message
215
 * @returns {Promise<Reference>} Renamed reference
216
 */
217
reference.rename(newName, force, logMessage): Promise<Reference>;
218

219
/**
220
 * Delete reference
221
 * @returns {Promise<void>}
222
 */
223
reference.delete(): Promise<void>;
224

225
/**
226
 * Peel reference to object type
227
 * @param {number} type - Target object type
228
 * @returns {Promise<Object>} Peeled object
229
 */
230
reference.peel(type): Promise<Object>;
231

232
/**
233
 * Get owning repository
234
 * @returns {Repository} Repository instance
235
 */
236
reference.owner(): Repository;
237
```
238

239
**Usage Examples:**
240

241
```javascript
242
// Examine reference properties
243
const ref = await NodeGit.Reference.lookup(repo, 'refs/heads/main');
244

245
console.log('Name:', ref.name());
246
console.log('Shorthand:', ref.shorthand());
247
console.log('Is branch:', ref.isBranch());
248
console.log('Is remote:', ref.isRemote());
249
console.log('Target SHA:', ref.target().tostrS());
250

251
// Update reference target
252
const newCommit = await repo.getHeadCommit();
253
await ref.setTarget(newCommit.id(), 'Updated branch target');
254

255
// Rename branch
256
await ref.rename('refs/heads/new-main', false, 'Renamed main branch');
257
```
258

259
### Branch Operations
260

261
High-level branch management operations.
262

263
```javascript { .api }
264
/**
265
 * Create new branch
266
 * @param {Repository} repo - Repository instance
267
 * @param {string} branchName - Branch name
268
 * @param {Commit|Oid} target - Target commit or OID
269
 * @param {boolean} force - Force creation if branch exists
270
 * @returns {Promise<Reference>} New branch reference
271
 */
272
Branch.create(repo, branchName, target, force): Promise<Reference>;
273

274
/**
275
 * Look up branch by name
276
 * @param {Repository} repo - Repository instance
277
 * @param {string} branchName - Branch name
278
 * @param {number} branchType - Branch type (LOCAL or REMOTE)
279
 * @returns {Promise<Reference>} Branch reference
280
 */
281
Branch.lookup(repo, branchName, branchType): Promise<Reference>;
282

283
/**
284
 * Delete branch
285
 * @param {Reference} branch - Branch reference to delete
286
 * @returns {Promise<void>}
287
 */
288
Branch.delete(branch): Promise<void>;
289

290
/**
291
 * Check if branch is HEAD
292
 * @param {Reference} branch - Branch reference
293
 * @returns {Promise<boolean>} True if branch is HEAD
294
 */
295
Branch.isHead(branch): Promise<boolean>;
296

297
/**
298
 * Move/rename branch
299
 * @param {Reference} branch - Branch to move
300
 * @param {string} newBranchName - New branch name
301
 * @param {boolean} force - Force move
302
 * @returns {Promise<Reference>} Moved branch reference
303
 */
304
Branch.move(branch, newBranchName, force): Promise<Reference>;
305

306
/**
307
 * Get branch name from reference
308
 * @param {Reference} ref - Branch reference
309
 * @returns {Promise<string>} Branch name
310
 */
311
Branch.name(ref): Promise<string>;
312

313
/**
314
 * Set upstream branch
315
 * @param {Reference} branch - Local branch
316
 * @param {string} upstreamName - Upstream branch name
317
 * @returns {Promise<void>}
318
 */
319
Branch.setUpstream(branch, upstreamName): Promise<void>;
320

321
/**
322
 * Get upstream branch
323
 * @param {Reference} branch - Local branch
324
 * @returns {Promise<Reference>} Upstream branch reference
325
 */
326
Branch.upstream(branch): Promise<Reference>;
327

328
/**
329
 * Get upstream name
330
 * @param {Repository} repo - Repository instance
331
 * @param {string} refname - Reference name
332
 * @returns {Promise<string>} Upstream name
333
 */
334
Branch.upstreamName(repo, refname): Promise<string>;
335

336
/**
337
 * Get remote name for branch
338
 * @param {Repository} repo - Repository instance
339
 * @param {string} refname - Reference name
340
 * @returns {Promise<string>} Remote name
341
 */
342
Branch.remoteName(repo, refname): Promise<string>;
343
```
344

345
**Usage Examples:**
346

347
```javascript
348
// Create new branch from HEAD
349
const headCommit = await repo.getHeadCommit();
350
const newBranch = await NodeGit.Branch.create(
351
  repo,
352
  'feature-xyz',
353
  headCommit,
354
  false
355
);
356

357
console.log('Created branch:', newBranch.shorthand());
358

359
// Look up branch
360
const mainBranch = await NodeGit.Branch.lookup(
361
  repo,
362
  'main',
363
  NodeGit.Branch.BRANCH.LOCAL
364
);
365

366
// Set up tracking
367
await NodeGit.Branch.setUpstream(newBranch, 'origin/main');
368

369
// Get upstream info
370
const upstream = await NodeGit.Branch.upstream(newBranch);
371
console.log('Upstream:', upstream.shorthand());
372

373
// Check if branch is current HEAD
374
const isHead = await NodeGit.Branch.isHead(newBranch);
375
console.log('Is HEAD branch:', isHead);
376

377
// Rename branch
378
const renamedBranch = await NodeGit.Branch.move(
379
  newBranch,
380
  'feature-new-name',
381
  false
382
);
383

384
// Delete branch
385
await NodeGit.Branch.delete(renamedBranch);
386
```
387

388
### Repository Branch Methods
389

390
Convenience methods on Repository for branch operations.
391

392
```javascript { .api }
393
/**
394
 * Create branch on repository
395
 * @param {string} name - Branch name
396
 * @param {Commit} target - Target commit
397
 * @param {boolean} force - Force creation
398
 * @returns {Promise<Reference>} New branch reference
399
 */
400
repository.createBranch(name, target, force): Promise<Reference>;
401

402
/**
403
 * Get branch reference
404
 * @param {string} name - Branch name
405
 * @returns {Promise<Reference>} Branch reference
406
 */
407
repository.getBranch(name): Promise<Reference>;
408

409
/**
410
 * Get current branch
411
 * @returns {Promise<Reference>} Current branch reference
412
 */
413
repository.getCurrentBranch(): Promise<Reference>;
414

415
/**
416
 * Checkout branch
417
 * @param {Reference|string} branch - Branch reference or name
418
 * @param {CheckoutOptions} opts - Checkout options
419
 * @returns {Promise<void>}
420
 */
421
repository.checkoutBranch(branch, opts): Promise<void>;
422

423
/**
424
 * Get branch commit
425
 * @param {string} branch - Branch name
426
 * @returns {Promise<Commit>} Branch tip commit
427
 */
428
repository.getBranchCommit(branch): Promise<Commit>;
429

430
/**
431
 * Get reference commit
432
 * @param {string} reference - Reference name
433
 * @returns {Promise<Commit>} Reference target commit
434
 */
435
repository.getReferenceCommit(reference): Promise<Commit>;
436
```
437

438
**Usage Examples:**
439

440
```javascript
441
// Repository-level branch operations
442
const commit = await repo.getHeadCommit();
443

444
// Create branch using repository method
445
const branch = await repo.createBranch('new-feature', commit, false);
446

447
// Get current branch
448
const current = await repo.getCurrentBranch();
449
console.log('Current branch:', current.shorthand());
450

451
// Checkout branch
452
await repo.checkoutBranch('new-feature', {
453
  strategy: NodeGit.Checkout.STRATEGY.SAFE
454
});
455

456
// Get branch tip commit
457
const branchCommit = await repo.getBranchCommit('new-feature');
458
console.log('Branch commit:', branchCommit.sha());
459
```
460

461
### Reflog Operations
462

463
Reference log management for tracking reference changes.
464

465
```javascript { .api }
466
/**
467
 * Ensure reflog exists for reference
468
 * @param {Repository} repo - Repository instance
469
 * @param {string} refname - Reference name
470
 * @returns {Promise<void>}
471
 */
472
Reference.ensureLog(repo, refname): Promise<void>;
473

474
/**
475
 * Check if reflog exists
476
 * @param {Repository} repo - Repository instance
477
 * @param {string} refname - Reference name
478
 * @returns {Promise<boolean>} True if reflog exists
479
 */
480
Reference.hasLog(repo, refname): Promise<boolean>;
481
```
482

483
**Usage Examples:**
484

485
```javascript
486
// Ensure reflog exists
487
await NodeGit.Reference.ensureLog(repo, 'refs/heads/main');
488

489
// Check if reflog exists
490
const hasLog = await NodeGit.Reference.hasLog(repo, 'refs/heads/feature');
491
if (hasLog) {
492
  console.log('Reflog exists for feature branch');
493
}
494
```
495

496
## Types
497

498
```javascript { .api }
499
// Reference types
500
Reference.TYPE = {
501
  INVALID: 0,
502
  OID: 1,
503
  SYMBOLIC: 2,
504
  LISTALL: 3
505
};
506

507
// Branch types
508
Branch.BRANCH = {
509
  LOCAL: 1,
510
  REMOTE: 2,
511
  ALL: 3
512
};
513

514
interface Reference {
515
  name(): string;
516
  shorthand(): string;
517
  target(): Oid;
518
  symbolicTarget(): string;
519
  type(): number;
520
  isBranch(): boolean;
521
  isRemote(): boolean;
522
  isTag(): boolean;
523
  isHead(): boolean;
524
  isConcrete(): boolean;
525
  owner(): Repository;
526
}
527

528
interface CheckoutOptions {
529
  strategy: number;
530
  disableFilters: boolean;
531
  dirMode: number;
532
  fileMode: number;
533
  fileOpenFlags: number;
534
  notifyFlags: number;
535
  notifyCallback: Function;
536
  progressCallback: Function;
537
  paths: string[];
538
  baseline: Tree;
539
  baselineIndex: Index;
540
  targetDirectory: string;
541
  ancestorLabel: string;
542
  ourLabel: string;
543
  theirLabel: string;
544
  perfdataCallback: Function;
545
}
546
```