0
# Reference Management
1

2
Managing Git references (branches, tags, HEAD).
3

4
## Capabilities
5

6
### Resolve Reference
7

8
Resolves a reference to its target object ID.
9

10
```javascript { .api }
11
/**
12
 * Resolve a reference to an object ID
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 - Reference name to resolve
17
 * @param args.depth - Maximum depth for symbolic references
18
 * @returns Promise resolving to object ID
19
 */
20
function resolveRef(args: {
21
  fs: FsClient;
22
  dir?: string;
23
  gitdir?: string;
24
  ref: string;
25
  depth?: number;
26
}): Promise<string>;
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
import git from "isomorphic-git";
33
import fs from "fs";
34

35
// Resolve HEAD to commit SHA
36
const headSha = await git.resolveRef({
37
  fs,
38
  dir: "/path/to/repo",
39
  ref: "HEAD"
40
});
41
console.log("HEAD points to:", headSha);
42

43
// Resolve branch to commit SHA  
44
const branchSha = await git.resolveRef({
45
  fs,
46
  dir: "/path/to/repo",
47
  ref: "main"
48
});
49
console.log("main branch points to:", branchSha);
50

51
// Resolve tag to object SHA
52
const tagSha = await git.resolveRef({
53
  fs,
54
  dir: "/path/to/repo",
55
  ref: "v1.0.0"
56
});
57
console.log("v1.0.0 tag points to:", tagSha);
58

59
// Resolve with full reference name
60
const fullRefSha = await git.resolveRef({
61
  fs,
62
  dir: "/path/to/repo",
63
  ref: "refs/heads/feature-branch"
64
});
65
console.log("refs/heads/feature-branch points to:", fullRefSha);
66
```
67

68
### Expand Reference
69

70
Expands a reference name to its full form.
71

72
```javascript { .api }
73
/**
74
 * Expand a reference name to full form
75
 * @param args.fs - File system client
76
 * @param args.dir - Working tree directory path
77
 * @param args.gitdir - Git directory path
78
 * @param args.ref - Reference name to expand
79
 * @returns Promise resolving to expanded reference name
80
 */
81
function expandRef(args: {
82
  fs: FsClient;
83
  dir?: string;
84
  gitdir?: string;
85
  ref: string;
86
}): Promise<string>;
87
```
88

89
**Usage Examples:**
90

91
```javascript
92
import git from "isomorphic-git";
93
import fs from "fs";
94

95
// Expand branch name
96
const expandedBranch = await git.expandRef({
97
  fs,
98
  dir: "/path/to/repo",
99
  ref: "main"
100
});
101
console.log("Expanded:", expandedBranch); // "refs/heads/main"
102

103
// Expand tag name
104
const expandedTag = await git.expandRef({
105
  fs,
106
  dir: "/path/to/repo",
107
  ref: "v1.0.0"
108
});
109
console.log("Expanded:", expandedTag); // "refs/tags/v1.0.0"
110

111
// Expand remote branch
112
const expandedRemote = await git.expandRef({
113
  fs,
114
  dir: "/path/to/repo",
115
  ref: "origin/main"
116
});
117
console.log("Expanded:", expandedRemote); // "refs/remotes/origin/main"
118
```
119

120
### List References
121

122
Lists all references in the repository.
123

124
```javascript { .api }
125
/**
126
 * List all references
127
 * @param args.fs - File system client
128
 * @param args.dir - Working tree directory path
129
 * @param args.gitdir - Git directory path
130
 * @returns Promise resolving to array of reference names
131
 */
132
function listRefs(args: {
133
  fs: FsClient;
134
  dir?: string;
135
  gitdir?: string;
136
}): Promise<string[]>;
137
```
138

139
**Usage Example:**
140

141
```javascript
142
import git from "isomorphic-git";
143
import fs from "fs";
144

145
const refs = await git.listRefs({
146
  fs,
147
  dir: "/path/to/repo"
148
});
149

150
console.log("All references:");
151
for (const ref of refs) {
152
  const sha = await git.resolveRef({ fs, dir: "/path/to/repo", ref });
153
  console.log(`${ref}: ${sha.slice(0, 8)}`);
154
}
155

156
// Filter by type
157
const branches = refs.filter(ref => ref.startsWith("refs/heads/"));
158
const tags = refs.filter(ref => ref.startsWith("refs/tags/"));
159
const remotes = refs.filter(ref => ref.startsWith("refs/remotes/"));
160

161
console.log("Branches:", branches);
162
console.log("Tags:", tags);
163
console.log("Remotes:", remotes);
164
```
165

166
### Write Reference
167

168
Creates or updates a reference.
169

170
```javascript { .api }
171
/**
172
 * Write a reference
173
 * @param args.fs - File system client 
174
 * @param args.dir - Working tree directory path
175
 * @param args.gitdir - Git directory path
176
 * @param args.ref - Reference name to write
177
 * @param args.value - Object ID or symbolic reference target  
178
 * @param args.force - Force update even if not fast-forward
179
 * @param args.symbolic - Create symbolic reference
180
 * @returns Promise resolving when reference is written
181
 */
182
function writeRef(args: {
183
  fs: FsClient;
184
  dir?: string;
185
  gitdir?: string;
186
  ref: string;
187
  value: string;
188
  force?: boolean;
189
  symbolic?: boolean;
190
}): Promise<void>;
191
```
192

193
**Usage Examples:**
194

195
```javascript
196
import git from "isomorphic-git";
197
import fs from "fs";
198

199
// Create new branch reference
200
await git.writeRef({
201
  fs,
202
  dir: "/path/to/repo",
203
  ref: "refs/heads/new-branch",
204
  value: "commit-sha-here"
205
});
206

207
// Update HEAD to point to different branch (symbolic reference)
208
await git.writeRef({
209
  fs,
210
  dir: "/path/to/repo",
211
  ref: "HEAD",
212
  value: "refs/heads/main",
213
  symbolic: true
214
});
215

216
// Force update reference
217
await git.writeRef({
218
  fs,
219
  dir: "/path/to/repo",
220
  ref: "refs/heads/main",
221
  value: "new-commit-sha",
222
  force: true
223
});
224

225
// Create lightweight tag
226
await git.writeRef({
227
  fs,
228
  dir: "/path/to/repo",
229
  ref: "refs/tags/v1.0.1",
230
  value: "commit-sha-here"
231
});
232
```
233

234
### Delete Reference
235

236
Deletes a reference.
237

238
```javascript { .api }
239
/**
240
 * Delete a reference
241
 * @param args.fs - File system client
242
 * @param args.dir - Working tree directory path
243
 * @param args.gitdir - Git directory path
244
 * @param args.ref - Reference name to delete
245
 * @returns Promise resolving when reference is deleted
246
 */
247
function deleteRef(args: {
248
  fs: FsClient;
249
  dir?: string;
250
  gitdir?: string;
251
  ref: string;
252
}): Promise<void>;
253
```
254

255
**Usage Examples:**
256

257
```javascript
258
import git from "isomorphic-git";
259
import fs from "fs";
260

261
// Delete a branch
262
await git.deleteRef({
263
  fs,
264
  dir: "/path/to/repo",
265
  ref: "refs/heads/old-branch"
266
});
267

268
// Delete a tag
269
await git.deleteRef({
270
  fs,
271
  dir: "/path/to/repo",
272
  ref: "refs/tags/old-tag"
273
});
274

275
// Delete remote tracking branch
276
await git.deleteRef({
277
  fs,
278
  dir: "/path/to/repo",
279
  ref: "refs/remotes/origin/deleted-branch"
280
});
281
```
282

283
### List Tags
284

285
Lists all tags in the repository.
286

287
```javascript { .api }
288
/**
289
 * List all tags
290
 * @param args.fs - File system client
291
 * @param args.dir - Working tree directory path
292
 * @param args.gitdir - Git directory path
293
 * @returns Promise resolving to array of tag names
294
 */
295
function listTags(args: {
296
  fs: FsClient;
297
  dir?: string;
298
  gitdir?: string;
299
}): Promise<string[]>;
300
```
301

302
**Usage Example:**
303

304
```javascript
305
import git from "isomorphic-git";
306
import fs from "fs";
307

308
const tags = await git.listTags({
309
  fs,
310
  dir: "/path/to/repo"
311
});
312

313
console.log("Available tags:");
314
for (const tag of tags) {
315
  console.log(`- ${tag}`);
316
  
317
  // Get what the tag points to
318
  const tagSha = await git.resolveRef({
319
    fs,
320
    dir: "/path/to/repo",
321
    ref: tag
322
  });
323
  console.log(`  Points to: ${tagSha.slice(0, 8)}`);
324
}
325
```
326

327
### Create Tag
328

329
Creates a lightweight tag pointing to a commit.
330

331
```javascript { .api }
332
/**
333
 * Create a lightweight tag
334
 * @param args.fs - File system client
335
 * @param args.dir - Working tree directory path
336
 * @param args.gitdir - Git directory path
337
 * @param args.ref - Tag name
338
 * @param args.object - Object ID to tag (defaults to HEAD)
339
 * @param args.force - Overwrite existing tag
340
 * @returns Promise resolving when tag is created
341
 */
342
function tag(args: {
343
  fs: FsClient;
344
  dir?: string;
345
  gitdir?: string;
346
  ref: string;
347
  object?: string;
348
  force?: boolean;
349
}): Promise<void>;
350
```
351

352
**Usage Examples:**
353

354
```javascript
355
import git from "isomorphic-git";  
356
import fs from "fs";
357

358
// Create tag pointing to HEAD
359
await git.tag({
360
  fs,
361
  dir: "/path/to/repo",
362
  ref: "v1.0.0"
363
});
364

365
// Create tag pointing to specific commit
366
await git.tag({
367
  fs,
368
  dir: "/path/to/repo",
369
  ref: "v0.9.0",
370
  object: "commit-sha-here"
371
});
372

373
// Force create tag (overwrite existing)
374
await git.tag({
375
  fs,
376
  dir: "/path/to/repo",
377
  ref: "latest",
378
  force: true
379
});
380
```
381

382
### Create Annotated Tag
383

384
Creates an annotated tag with metadata.
385

386
```javascript { .api }
387
/**
388
 * Create an annotated tag
389
 * @param args.fs - File system client
390
 * @param args.dir - Working tree directory path
391
 * @param args.gitdir - Git directory path
392
 * @param args.ref - Tag name
393
 * @param args.message - Tag message
394
 * @param args.object - Object ID to tag (defaults to HEAD)
395
 * @param args.tagger - Tagger information
396
 * @param args.signingKey - PGP signing key
397
 * @param args.force - Overwrite existing tag
398
 * @returns Promise resolving when tag is created
399
 */
400
function annotatedTag(args: {
401
  fs: FsClient;
402
  dir?: string;
403
  gitdir?: string;
404
  ref: string;
405
  message: string;
406
  object?: string;
407
  tagger?: PersonObject;
408
  signingKey?: string;
409
  force?: boolean;
410
}): Promise<void>;
411
```
412

413
**Usage Example:**
414

415
```javascript
416
import git from "isomorphic-git";
417
import fs from "fs";
418

419
// Create annotated tag
420
await git.annotatedTag({
421
  fs,
422
  dir: "/path/to/repo",
423
  ref: "v1.0.0",
424
  message: "Release version 1.0.0\n\nThis is a major release with new features.",
425
  tagger: {
426
    name: "Release Manager",
427
    email: "releases@example.com"
428
  }
429
});
430
```
431

432
### Delete Tag
433

434
Deletes a tag.
435

436
```javascript { .api }
437
/**
438
 * Delete a tag
439
 * @param args.fs - File system client
440
 * @param args.dir - Working tree directory path
441
 * @param args.gitdir - Git directory path
442
 * @param args.ref - Tag name to delete
443
 * @returns Promise resolving when tag is deleted
444
 */
445
function deleteTag(args: {
446
  fs: FsClient;
447
  dir?: string;
448
  gitdir?: string;
449
  ref: string;
450
}): Promise<void>;
451
```
452

453
**Usage Example:**
454

455
```javascript
456
import git from "isomorphic-git";
457
import fs from "fs";
458

459
// Delete a tag
460
await git.deleteTag({
461
  fs,
462
  dir: "/path/to/repo",
463
  ref: "old-tag"
464
});
465
```
466

467
## Reference Types and Patterns
468

469
### Branch References
470

471
Branch references are stored under `refs/heads/`:
472

473
```javascript
474
import git from "isomorphic-git";
475
import fs from "fs";
476

477
// Full branch reference names
478
const branches = [
479
  "refs/heads/main",
480
  "refs/heads/develop",
481
  "refs/heads/feature/new-ui"
482
];
483

484
// List all local branches
485
const refs = await git.listRefs({ fs, dir: "/path/to/repo" });
486
const localBranches = refs
487
  .filter(ref => ref.startsWith("refs/heads/"))
488
  .map(ref => ref.replace("refs/heads/", ""));
489

490
console.log("Local branches:", localBranches);
491
```
492

493
### Tag References
494

495
Tag references are stored under `refs/tags/`:
496

497
```javascript
498
import git from "isomorphic-git";
499
import fs from "fs";
500

501
// Full tag reference names
502
const tagRefs = [
503
  "refs/tags/v1.0.0",
504
  "refs/tags/v1.1.0", 
505
  "refs/tags/beta-1"
506
];
507

508
// List all tags
509
const allTags = await git.listTags({ fs, dir: "/path/to/repo" });
510
console.log("All tags:", allTags);
511
```
512

513
### Remote Tracking References
514

515
Remote tracking references are stored under `refs/remotes/`:
516

517
```javascript
518
import git from "isomorphic-git";
519
import fs from "fs";
520

521
// Remote tracking branch references
522
const remoteRefs = [
523
  "refs/remotes/origin/main",
524
  "refs/remotes/origin/develop",
525
  "refs/remotes/upstream/main"
526
];
527

528
// List all remote tracking branches
529
const refs = await git.listRefs({ fs, dir: "/path/to/repo" });
530
const remoteBranches = refs
531
  .filter(ref => ref.startsWith("refs/remotes/"))
532
  .map(ref => ref.replace("refs/remotes/", ""));
533

534
console.log("Remote branches:", remoteBranches);
535
```
536

537
### Special References
538

539
```javascript
540
import git from "isomorphic-git";
541
import fs from "fs";
542

543
// HEAD - current branch/commit
544
const head = await git.resolveRef({
545
  fs,
546
  dir: "/path/to/repo",
547
  ref: "HEAD"
548
});
549

550
// Check if HEAD is symbolic (points to branch) or direct (detached)
551
try {
552
  const currentBranch = await git.currentBranch({
553
    fs,
554
    dir: "/path/to/repo"
555
  });
556
  if (currentBranch) {
557
    console.log("On branch:", currentBranch);
558
  } else {
559
    console.log("Detached HEAD at:", head.slice(0, 8));
560
  }
561
} catch (err) {
562
  console.log("Detached HEAD at:", head.slice(0, 8));
563
}
564
```