0
# Git Objects
1

2
Access to core Git objects including commits, trees, blobs, and tags. These classes provide full access to Git's object database and represent the four fundamental object types in Git's content-addressable storage system.
3

4
## Capabilities
5

6
### Base Object Class
7

8
The base class for all Git objects providing common functionality for object lookup and type management.
9

10
```javascript { .api }
11
/**
12
 * Look up any Git object by OID and type
13
 * @param {Repository} repo - Repository instance
14
 * @param {Oid} id - Object ID
15
 * @param {number} type - Object type constant
16
 * @returns {Promise<Object>} Git object of specified type
17
 */
18
Object.lookup(repo, id, type): Promise<Object>;
19

20
/**
21
 * Look up object by path in a tree
22
 * @param {Repository} repo - Repository instance
23
 * @param {Tree} tree - Tree to search in
24
 * @param {string} path - Path to object
25
 * @param {number} type - Expected object type
26
 * @returns {Promise<Object>} Object at path
27
 */
28
Object.lookupByPath(repo, tree, path, type): Promise<Object>;
29

30
/**
31
 * Convert string to object type constant
32
 * @param {string} str - Type string ('commit', 'tree', 'blob', 'tag')
33
 * @returns {number} Object type constant
34
 */
35
Object.string2Type(str): number;
36

37
/**
38
 * Convert object type constant to string
39
 * @param {number} type - Object type constant
40
 * @returns {string} Type string
41
 */
42
Object.type2String(type): string;
43
```
44

45
**Object Types:**
46

47
```javascript { .api }
48
Object.TYPE = {
49
  ANY: -2,
50
  BAD: -1,
51
  COMMIT: 1,
52
  TREE: 2,
53
  BLOB: 3,
54
  TAG: 4,
55
  OFS_DELTA: 6,
56
  REF_DELTA: 7
57
};
58
```
59

60
### Commit Objects
61

62
Git commit objects represent snapshots in the repository history with metadata about authorship, timing, and parent relationships.
63

64
```javascript { .api }
65
/**
66
 * Look up commit by OID
67
 * @param {Repository} repo - Repository instance
68
 * @param {Oid} oid - Object ID of commit
69
 * @returns {Promise<Commit>} Commit object
70
 */
71
Commit.lookup(repo, oid): Promise<Commit>;
72

73
/**
74
 * Create a new commit
75
 * @param {Repository} repo - Repository instance
76
 * @param {string} updateRef - Reference to update (e.g., "HEAD")
77
 * @param {Signature} author - Author signature
78
 * @param {Signature} committer - Committer signature
79
 * @param {string} encoding - Message encoding
80
 * @param {string} message - Commit message
81
 * @param {Tree} tree - Tree object for commit
82
 * @param {number} parentCount - Number of parents
83
 * @param {Commit[]} parents - Parent commits
84
 * @returns {Promise<Oid>} New commit OID
85
 */
86
Commit.create(repo, updateRef, author, committer, encoding, message, tree, parentCount, parents): Promise<Oid>;
87

88
/**
89
 * Create commit with signature
90
 * @param {Repository} repo - Repository instance
91
 * @param {string} commitContent - Raw commit content
92
 * @param {string} signature - GPG signature
93
 * @param {string} signatureField - Signature field name
94
 * @returns {Promise<Oid>} New commit OID
95
 */
96
Commit.createWithSignature(repo, commitContent, signature, signatureField): Promise<Oid>;
97
```
98

99
**Commit Instance Methods:**
100

101
```javascript { .api }
102
/**
103
 * Get commit object ID
104
 * @returns {Oid} Commit OID
105
 */
106
commit.id(): Oid;
107

108
/**
109
 * Get commit SHA as string
110
 * @returns {string} SHA string
111
 */
112
commit.sha(): string;
113

114
/**
115
 * Get commit message
116
 * @returns {string} Commit message
117
 */
118
commit.message(): string;
119

120
/**
121
 * Get commit summary (first line of message)
122
 * @returns {string} Commit summary
123
 */
124
commit.summary(): string;
125

126
/**
127
 * Get raw commit message
128
 * @returns {string} Raw message
129
 */
130
commit.messageRaw(): string;
131

132
/**
133
 * Get message encoding
134
 * @returns {string} Message encoding
135
 */
136
commit.messageEncoding(): string;
137

138
/**
139
 * Get author signature
140
 * @returns {Signature} Author signature
141
 */
142
commit.author(): Signature;
143

144
/**
145
 * Get committer signature
146
 * @returns {Signature} Committer signature
147
 */
148
commit.committer(): Signature;
149

150
/**
151
 * Get commit time
152
 * @returns {number} Commit timestamp
153
 */
154
commit.time(): number;
155

156
/**
157
 * Get commit timezone offset
158
 * @returns {number} Timezone offset
159
 */
160
commit.timeOffset(): number;
161

162
/**
163
 * Get commit tree
164
 * @returns {Promise<Tree>} Tree object
165
 */
166
commit.getTree(): Promise<Tree>;
167

168
/**
169
 * Get tree OID
170
 * @returns {Oid} Tree OID
171
 */
172
commit.treeId(): Oid;
173

174
/**
175
 * Get number of parents
176
 * @returns {number} Parent count
177
 */
178
commit.parentcount(): number;
179

180
/**
181
 * Get parent commit by index
182
 * @param {number} n - Parent index
183
 * @returns {Promise<Commit>} Parent commit
184
 */
185
commit.parent(n): Promise<Commit>;
186

187
/**
188
 * Get parent OID by index
189
 * @param {number} n - Parent index
190
 * @returns {Oid} Parent OID
191
 */
192
commit.parentId(n): Oid;
193

194
/**
195
 * Get all parent commits
196
 * @returns {Promise<Commit[]>} Array of parent commits
197
 */
198
commit.getParents(): Promise<Commit[]>;
199

200
/**
201
 * Get diff for this commit
202
 * @returns {Promise<Diff>} Diff object
203
 */
204
commit.getDiff(): Promise<Diff>;
205

206
/**
207
 * Get diff with options
208
 * @param {DiffOptions} options - Diff options
209
 * @returns {Promise<Diff>} Diff object
210
 */
211
commit.getDiffWithOptions(options): Promise<Diff>;
212
```
213

214
**Usage Examples:**
215

216
```javascript
217
const NodeGit = require('nodegit');
218

219
// Look up commit by SHA
220
const repo = await NodeGit.Repository.open('./my-repo');
221
const oid = NodeGit.Oid.fromString('a1b2c3d4e5f6...');
222
const commit = await NodeGit.Commit.lookup(repo, oid);
223

224
console.log('Commit SHA:', commit.sha());
225
console.log('Author:', commit.author().name());
226
console.log('Message:', commit.message());
227
console.log('Parent count:', commit.parentcount());
228

229
// Get commit tree and parents
230
const tree = await commit.getTree();
231
const parents = await commit.getParents();
232

233
// Create new commit
234
const signature = NodeGit.Signature.now('John Doe', 'john@example.com');
235
const index = await repo.index();
236
const treeOid = await index.writeTree();
237
const tree = await NodeGit.Tree.lookup(repo, treeOid);
238

239
const newCommitOid = await NodeGit.Commit.create(
240
  repo,
241
  'HEAD',
242
  signature,
243
  signature,
244
  null,
245
  'New commit message',
246
  tree,
247
  1,
248
  [commit]
249
);
250
```
251

252
### Tree Objects
253

254
Git tree objects represent directory snapshots, containing references to blobs (files) and other trees (subdirectories).
255

256
```javascript { .api }
257
/**
258
 * Look up tree by OID
259
 * @param {Repository} repo - Repository instance
260
 * @param {Oid} oid - Object ID of tree
261
 * @returns {Promise<Tree>} Tree object
262
 */
263
Tree.lookup(repo, oid): Promise<Tree>;
264

265
/**
266
 * Get tree entry by index
267
 * @param {Tree} tree - Tree object
268
 * @param {number} idx - Entry index
269
 * @returns {TreeEntry} Tree entry
270
 */
271
Tree.entryByIndex(tree, idx): TreeEntry;
272

273
/**
274
 * Get tree entry by OID
275
 * @param {Tree} tree - Tree object
276
 * @param {Oid} oid - Entry OID
277
 * @returns {TreeEntry} Tree entry
278
 */
279
Tree.entryById(tree, oid): TreeEntry;
280

281
/**
282
 * Get tree entry by name
283
 * @param {Tree} tree - Tree object
284
 * @param {string} name - Entry name
285
 * @returns {TreeEntry} Tree entry
286
 */
287
Tree.entryByName(tree, name): TreeEntry;
288

289
/**
290
 * Get tree entry by path
291
 * @param {Tree} tree - Tree object
292
 * @param {string} path - Entry path
293
 * @returns {Promise<TreeEntry>} Tree entry
294
 */
295
Tree.entryByPath(tree, path): Promise<TreeEntry>;
296
```
297

298
**Tree Instance Methods:**
299

300
```javascript { .api }
301
/**
302
 * Get tree object ID
303
 * @returns {Oid} Tree OID
304
 */
305
tree.id(): Oid;
306

307
/**
308
 * Get number of entries in tree
309
 * @returns {number} Entry count
310
 */
311
tree.entryCount(): number;
312

313
/**
314
 * Get all tree entries
315
 * @returns {TreeEntry[]} Array of tree entries
316
 */
317
tree.entries(): TreeEntry[];
318

319
/**
320
 * Get entry by index
321
 * @param {number} idx - Entry index
322
 * @returns {TreeEntry} Tree entry
323
 */
324
tree.entryByIndex(idx): TreeEntry;
325

326
/**
327
 * Get entry by name
328
 * @param {string} name - Entry name
329
 * @returns {TreeEntry} Tree entry
330
 */
331
tree.entryByName(name): TreeEntry;
332

333
/**
334
 * Get entry by path
335
 * @param {string} path - Entry path
336
 * @returns {Promise<TreeEntry>} Tree entry
337
 */
338
tree.getEntry(path): Promise<TreeEntry>;
339

340
/**
341
 * Walk tree entries recursively
342
 * @param {Function} callback - Callback for each entry
343
 * @returns {Promise<void>}
344
 */
345
tree.walk(callback): Promise<void>;
346

347
/**
348
 * Create diff between trees
349
 * @param {Tree} tree - Tree to compare with
350
 * @returns {Promise<Diff>} Diff object
351
 */
352
tree.diff(tree): Promise<Diff>;
353

354
/**
355
 * Create diff with options
356
 * @param {Tree} tree - Tree to compare with
357
 * @param {DiffOptions} options - Diff options
358
 * @returns {Promise<Diff>} Diff object
359
 */
360
tree.diffWithOptions(tree, options): Promise<Diff>;
361
```
362

363
**Usage Examples:**
364

365
```javascript
366
// Get tree from commit
367
const commit = await repo.getHeadCommit();
368
const tree = await commit.getTree();
369

370
console.log('Tree entries:', tree.entryCount());
371

372
// Walk through all entries
373
tree.entries().forEach(function(entry) {
374
  console.log('Name:', entry.name());
375
  console.log('Type:', entry.isFile() ? 'file' : 'directory');
376
  console.log('Mode:', entry.filemode().toString(8));
377
});
378

379
// Get specific file entry
380
const fileEntry = tree.entryByName('README.md');
381
if (fileEntry) {
382
  const blob = await fileEntry.getBlob();
383
  console.log('File content:', blob.toString());
384
}
385

386
// Walk tree recursively
387
await tree.walk(function(root, entry) {
388
  console.log('Path:', root + entry.name());
389
  return 0; // Continue walking
390
});
391
```
392

393
### Blob Objects
394

395
Git blob objects store file content data.
396

397
```javascript { .api }
398
/**
399
 * Look up blob by OID
400
 * @param {Repository} repo - Repository instance
401
 * @param {Oid} oid - Object ID of blob
402
 * @returns {Promise<Blob>} Blob object
403
 */
404
Blob.lookup(repo, oid): Promise<Blob>;
405

406
/**
407
 * Create blob from buffer
408
 * @param {Repository} repo - Repository instance
409
 * @param {Buffer} buffer - Content buffer
410
 * @param {number} len - Buffer length
411
 * @returns {Promise<Oid>} New blob OID
412
 */
413
Blob.createFromBuffer(repo, buffer, len): Promise<Oid>;
414

415
/**
416
 * Create blob from working directory file
417
 * @param {Repository} repo - Repository instance
418
 * @param {string} relativePath - Relative path to file
419
 * @returns {Promise<Oid>} New blob OID
420
 */
421
Blob.createFromWorkdir(repo, relativePath): Promise<Oid>;
422

423
/**
424
 * Create blob from disk file
425
 * @param {Repository} repo - Repository instance
426
 * @param {string} path - Absolute path to file
427
 * @returns {Promise<Oid>} New blob OID
428
 */
429
Blob.createFromDisk(repo, path): Promise<Oid>;
430

431
/**
432
 * Create blob from stream
433
 * @param {Repository} repo - Repository instance
434
 * @param {string} hintPath - Hint path for filters
435
 * @returns {Promise<WriteStream>} Write stream for blob
436
 */
437
Blob.createFromStream(repo, hintPath): Promise<WriteStream>;
438
```
439

440
**Blob Instance Methods:**
441

442
```javascript { .api }
443
/**
444
 * Get blob object ID
445
 * @returns {Oid} Blob OID
446
 */
447
blob.id(): Oid;
448

449
/**
450
 * Get raw content as buffer
451
 * @returns {Buffer} Raw content
452
 */
453
blob.rawcontent(): Buffer;
454

455
/**
456
 * Get content as buffer
457
 * @returns {Buffer} Content buffer
458
 */
459
blob.content(): Buffer;
460

461
/**
462
 * Get content as string
463
 * @returns {string} Content string
464
 */
465
blob.toString(): string;
466

467
/**
468
 * Get raw content size
469
 * @returns {number} Size in bytes
470
 */
471
blob.rawsize(): number;
472

473
/**
474
 * Check if blob is binary
475
 * @returns {boolean} True if binary
476
 */
477
blob.isBinary(): boolean;
478

479
/**
480
 * Get file mode for blob
481
 * @returns {number} File mode
482
 */
483
blob.filemode(): number;
484
```
485

486
**Usage Examples:**
487

488
```javascript
489
// Create blob from string content
490
const content = "Hello, World!";
491
const buffer = Buffer.from(content);
492
const blobOid = await NodeGit.Blob.createFromBuffer(repo, buffer, buffer.length);
493

494
// Look up blob and read content
495
const blob = await NodeGit.Blob.lookup(repo, blobOid);
496
console.log('Blob size:', blob.rawsize());
497
console.log('Is binary:', blob.isBinary());
498
console.log('Content:', blob.toString());
499

500
// Create blob from file
501
const fileOid = await NodeGit.Blob.createFromWorkdir(repo, 'README.md');
502
const fileBlob = await NodeGit.Blob.lookup(repo, fileOid);
503
console.log('File content:', fileBlob.toString());
504
```
505

506
### Tag Objects
507

508
Git tag objects store tag information and references to tagged objects.
509

510
```javascript { .api }
511
/**
512
 * Look up tag by OID
513
 * @param {Repository} repo - Repository instance
514
 * @param {Oid} oid - Object ID of tag
515
 * @returns {Promise<Tag>} Tag object
516
 */
517
Tag.lookup(repo, oid): Promise<Tag>;
518

519
/**
520
 * Create annotated tag
521
 * @param {Repository} repo - Repository instance
522
 * @param {string} tagName - Tag name
523
 * @param {Object} target - Target object
524
 * @param {Signature} tagger - Tagger signature
525
 * @param {string} message - Tag message
526
 * @param {boolean} force - Force creation
527
 * @returns {Promise<Oid>} New tag OID
528
 */
529
Tag.create(repo, tagName, target, tagger, message, force): Promise<Oid>;
530

531
/**
532
 * Create lightweight tag
533
 * @param {Repository} repo - Repository instance
534
 * @param {string} tagName - Tag name
535
 * @param {Object} target - Target object
536
 * @param {boolean} force - Force creation
537
 * @returns {Promise<Oid>} New tag OID
538
 */
539
Tag.createLightweight(repo, tagName, target, force): Promise<Oid>;
540

541
/**
542
 * List all tags
543
 * @param {Repository} repo - Repository instance
544
 * @returns {Promise<string[]>} Array of tag names
545
 */
546
Tag.list(repo): Promise<string[]>;
547

548
/**
549
 * List tags matching pattern
550
 * @param {string} pattern - Tag pattern
551
 * @param {Repository} repo - Repository instance
552
 * @returns {Promise<string[]>} Array of matching tag names
553
 */
554
Tag.listMatch(pattern, repo): Promise<string[]>;
555

556
/**
557
 * Delete tag
558
 * @param {Repository} repo - Repository instance
559
 * @param {string} tagName - Tag name to delete
560
 * @returns {Promise<void>}
561
 */
562
Tag.delete(repo, tagName): Promise<void>;
563
```
564

565
**Tag Instance Methods:**
566

567
```javascript { .api }
568
/**
569
 * Get tag object ID
570
 * @returns {Oid} Tag OID
571
 */
572
tag.id(): Oid;
573

574
/**
575
 * Get tag name
576
 * @returns {string} Tag name
577
 */
578
tag.name(): string;
579

580
/**
581
 * Get tag message
582
 * @returns {string} Tag message
583
 */
584
tag.message(): string;
585

586
/**
587
 * Get tagger signature
588
 * @returns {Signature} Tagger signature
589
 */
590
tag.tagger(): Signature;
591

592
/**
593
 * Get tagged object
594
 * @returns {Promise<Object>} Tagged object
595
 */
596
tag.target(): Promise<Object>;
597

598
/**
599
 * Get target object ID
600
 * @returns {Oid} Target OID
601
 */
602
tag.targetId(): Oid;
603

604
/**
605
 * Get target object type
606
 * @returns {number} Target type
607
 */
608
tag.targetType(): number;
609

610
/**
611
 * Peel tag to target object
612
 * @returns {Promise<Object>} Target object
613
 */
614
tag.peel(): Promise<Object>;
615
```
616

617
**Usage Examples:**
618

619
```javascript
620
// Create annotated tag
621
const signature = NodeGit.Signature.now('John Doe', 'john@example.com');
622
const commit = await repo.getHeadCommit();
623

624
const tagOid = await NodeGit.Tag.create(
625
  repo,
626
  'v1.0.0',
627
  commit,
628
  signature,
629
  'Release version 1.0.0',
630
  false
631
);
632

633
// Create lightweight tag
634
await NodeGit.Tag.createLightweight(repo, 'latest', commit, false);
635

636
// List all tags
637
const tags = await NodeGit.Tag.list(repo);
638
console.log('Tags:', tags);
639

640
// Look up and examine tag
641
const tag = await NodeGit.Tag.lookup(repo, tagOid);
642
console.log('Tag name:', tag.name());
643
console.log('Tag message:', tag.message());
644
console.log('Tagger:', tag.tagger().name());
645

646
// Get tagged commit
647
const taggedCommit = await tag.target();
648
console.log('Tagged commit:', taggedCommit.sha());
649
```
650

651
## Types
652

653
```javascript { .api }
654
interface TreeEntry {
655
  name(): string;
656
  oid(): Oid;
657
  filemode(): number;
658
  type(): number;
659
  isFile(): boolean;
660
  isTree(): boolean;
661
  getBlob(): Promise<Blob>;
662
}
663

664
interface Signature {
665
  name(): string;
666
  email(): string;
667
  when(): Time;
668
}
669

670
interface Time {
671
  time: number;
672
  offset: number;
673
}
674

675
interface Oid {
676
  tostrS(): string;
677
  fmt(): string;
678
  equal(b: Oid): boolean;
679
  cmp(b: Oid): number;
680
}
681

682
// Object type constants
683
Object.TYPE = {
684
  ANY: -2,
685
  BAD: -1,
686
  COMMIT: 1,
687
  TREE: 2,
688
  BLOB: 3,
689
  TAG: 4
690
};
691
```