0
# Object Operations
1

2
Low-level operations for reading and writing Git objects (blobs, commits, trees, tags).
3

4
## Capabilities
5

6
### Read Git Object
7

8
Reads any Git object from the repository.
9

10
```javascript { .api }
11
/**
12
 * Read a Git object
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.oid - Object ID (SHA-1 hash)
17
 * @param args.format - Object format ('content', 'wrapped', 'deflated', 'parsed')
18
 * @param args.filepath - File path for blob objects
19
 * @param args.encoding - Text encoding for content
20
 * @returns Promise resolving to object data
21
 */
22
function readObject(args: {
23
  fs: FsClient;
24
  dir?: string;
25
  gitdir?: string;
26
  oid: string;
27
  format?: string;
28
  filepath?: string;
29
  encoding?: string;
30
}): Promise<ReadObjectResult>;
31
```
32

33
**Usage Examples:**
34

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

39
// Read any object by SHA
40
const object = await git.readObject({
41
  fs,
42
  dir: "/path/to/repo",
43
  oid: "abc123...",
44
  format: "parsed"
45
});
46

47
console.log("Object type:", object.type);
48
console.log("Object content:", object.object);
49

50
// Read object content as string
51
const textObject = await git.readObject({
52
  fs,
53
  dir: "/path/to/repo", 
54
  oid: "def456...",
55
  format: "content",
56
  encoding: "utf8"
57
});
58
console.log("Content:", textObject.object);
59
```
60

61
### Write Git Object
62

63
Writes a Git object to the repository.
64

65
```javascript { .api }
66
/**
67
 * Write a Git object
68
 * @param args.fs - File system client
69
 * @param args.dir - Working tree directory path
70
 * @param args.gitdir - Git directory path
71
 * @param args.type - Object type ('blob', 'tree', 'commit', 'tag')
72
 * @param args.object - Object data as Uint8Array
73
 * @param args.format - Input format ('content', 'wrapped', 'deflated', 'parsed')
74
 * @param args.oid - Expected object ID for verification
75
 * @param args.encoding - Text encoding for content
76
 * @returns Promise resolving to object SHA
77
 */
78
function writeObject(args: {
79
  fs: FsClient;
80
  dir?: string;
81
  gitdir?: string;
82
  type: string;
83
  object: Uint8Array;
84
  format?: string;
85
  oid?: string;
86
  encoding?: string;
87
}): Promise<string>;
88
```
89

90
**Usage Example:**
91

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

96
// Write a blob object
97
const content = new TextEncoder().encode("Hello, World!");
98
const blobSha = await git.writeObject({
99
  fs,
100
  dir: "/path/to/repo",
101
  type: "blob",
102
  object: content
103
});
104
console.log("Created blob:", blobSha);
105
```
106

107
### Read Blob Object
108

109
Reads a blob (file content) object.
110

111
```javascript { .api }
112
/**
113
 * Read a blob object
114
 * @param args.fs - File system client
115
 * @param args.dir - Working tree directory path
116
 * @param args.gitdir - Git directory path
117
 * @param args.oid - Blob object ID
118
 * @param args.filepath - File path context
119
 * @returns Promise resolving to blob data
120
 */
121
function readBlob(args: {
122
  fs: FsClient;
123
  dir?: string;
124
  gitdir?: string;
125
  oid: string;
126
  filepath?: string;
127
}): Promise<ReadBlobResult>;
128
```
129

130
**Usage Example:**
131

132
```javascript
133
import git from "isomorphic-git";
134
import fs from "fs";
135

136
const blob = await git.readBlob({
137
  fs,
138
  dir: "/path/to/repo",
139
  oid: "blob-sha-here"
140
});
141

142
console.log("Blob content:", new TextDecoder().decode(blob.blob));
143
```
144

145
### Write Blob Object
146

147
Creates a blob object from data.
148

149
```javascript { .api }
150
/**
151
 * Write a blob object
152
 * @param args.fs - File system client
153
 * @param args.dir - Working tree directory path
154
 * @param args.gitdir - Git directory path
155
 * @param args.blob - Blob data as Uint8Array
156
 * @returns Promise resolving to blob SHA
157
 */
158
function writeBlob(args: {
159
  fs: FsClient;
160
  dir?: string;
161
  gitdir?: string;
162
  blob: Uint8Array;
163
}): Promise<string>;
164
```
165

166
**Usage Example:**
167

168
```javascript
169
import git from "isomorphic-git";
170
import fs from "fs";
171

172
const fileContent = await fs.promises.readFile("./myfile.txt");
173
const blobSha = await git.writeBlob({
174
  fs,
175
  dir: "/path/to/repo",
176
  blob: fileContent
177
});
178
console.log("Created blob:", blobSha);
179
```
180

181
### Hash Blob Data
182

183
Calculates the SHA-1 hash of blob data without writing to repository.
184

185
```javascript { .api }
186
/**
187
 * Calculate SHA-1 hash of blob data
188
 * @param args.object - Blob data as Uint8Array
189
 * @returns Promise resolving to SHA-1 hash
190
 */
191
function hashBlob(args: {
192
  object: Uint8Array;
193
}): Promise<string>;
194
```
195

196
**Usage Example:**
197

198
```javascript
199
import git from "isomorphic-git";
200

201
const content = new TextEncoder().encode("Hello, World!");
202
const hash = await git.hashBlob({ object: content });
203
console.log("Hash:", hash);
204
```
205

206
### Read Tree Object
207

208
Reads a tree (directory listing) object.
209

210
```javascript { .api }
211
/**
212
 * Read a tree object
213
 * @param args.fs - File system client
214
 * @param args.dir - Working tree directory path
215
 * @param args.gitdir - Git directory path
216
 * @param args.oid - Tree object ID
217
 * @param args.filepath - File path context
218
 * @returns Promise resolving to tree entries
219
 */
220
function readTree(args: {
221
  fs: FsClient;
222
  dir?: string;
223
  gitdir?: string;
224
  oid: string;
225
  filepath?: string;
226
}): Promise<ReadTreeResult>;
227
```
228

229
**Usage Example:**
230

231
```javascript
232
import git from "isomorphic-git";
233
import fs from "fs";
234

235
const tree = await git.readTree({
236
  fs,
237
  dir: "/path/to/repo",
238
  oid: "tree-sha-here"
239
});
240

241
for (const entry of tree.tree) {
242
  console.log(`${entry.mode} ${entry.type} ${entry.oid} ${entry.path}`);
243
}
244
```
245

246
### Write Tree Object
247

248
Creates a tree object.
249

250
```javascript { .api }
251
/**
252
 * Write a tree object
253
 * @param args.fs - File system client
254
 * @param args.dir - Working tree directory path
255
 * @param args.gitdir - Git directory path
256
 * @param args.tree - Tree entries
257
 * @returns Promise resolving to tree SHA
258
 */
259
function writeTree(args: {
260
  fs: FsClient;
261
  dir?: string;
262
  gitdir?: string;
263
  tree: TreeEntry[];
264
}): Promise<string>;
265
```
266

267
**Usage Example:**
268

269
```javascript
270
import git from "isomorphic-git";
271
import fs from "fs";
272

273
const treeSha = await git.writeTree({
274
  fs,
275
  dir: "/path/to/repo",
276
  tree: [
277
    {
278
      mode: "100644",
279
      path: "README.md",
280
      oid: "blob-sha-here",
281
      type: "blob"
282
    },
283
    {
284
      mode: "040000", 
285
      path: "src",
286
      oid: "subtree-sha-here",
287
      type: "tree"
288
    }
289
  ]
290
});
291
console.log("Created tree:", treeSha);
292
```
293

294
### Read Tag Object
295

296
Reads an annotated tag object.
297

298
```javascript { .api }
299
/**
300
 * Read a tag object
301
 * @param args.fs - File system client
302
 * @param args.dir - Working tree directory path
303
 * @param args.gitdir - Git directory path
304
 * @param args.oid - Tag object ID
305
 * @returns Promise resolving to tag data
306
 */
307
function readTag(args: {
308
  fs: FsClient;
309
  dir?: string;
310
  gitdir?: string;
311
  oid: string;
312
}): Promise<ReadTagResult>;
313
```
314

315
**Usage Example:**
316

317
```javascript
318
import git from "isomorphic-git";
319
import fs from "fs";
320

321
const tag = await git.readTag({
322
  fs,
323
  dir: "/path/to/repo",
324
  oid: "tag-sha-here"
325
});
326

327
console.log("Tag name:", tag.tag.tag);
328
console.log("Tag message:", tag.tag.message);
329
console.log("Tagged object:", tag.tag.object);
330
console.log("Tagger:", tag.tag.tagger);
331
```
332

333
### Write Tag Object
334

335
Creates an annotated tag object.
336

337
```javascript { .api }
338
/**
339
 * Write a tag object
340
 * @param args.fs - File system client
341
 * @param args.dir - Working tree directory path
342
 * @param args.gitdir - Git directory path
343
 * @param args.tag - Tag data
344
 * @returns Promise resolving to tag SHA
345
 */
346
function writeTag(args: {
347
  fs: FsClient;
348
  dir?: string;
349
  gitdir?: string;
350
  tag: TagObject;
351
}): Promise<string>;
352
```
353

354
**Usage Example:**
355

356
```javascript
357
import git from "isomorphic-git";
358
import fs from "fs";
359

360
const tagSha = await git.writeTag({
361
  fs,
362
  dir: "/path/to/repo",
363
  tag: {
364
    object: "commit-sha-here",
365
    type: "commit",
366
    tag: "v1.0.0",
367
    message: "Release version 1.0.0",
368
    tagger: {
369
      name: "Tagger Name",
370
      email: "tagger@example.com",
371
      timestamp: Math.floor(Date.now() / 1000),
372
      timezoneOffset: new Date().getTimezoneOffset()
373
    }
374
  }
375
});
376
console.log("Created tag:", tagSha);
377
```
378

379
### Expand Object ID
380

381
Expands abbreviated object IDs to full SHA-1 hashes.
382

383
```javascript { .api }
384
/**
385
 * Expand abbreviated object ID
386
 * @param args.fs - File system client
387
 * @param args.dir - Working tree directory path
388
 * @param args.gitdir - Git directory path
389
 * @param args.oid - Abbreviated object ID
390
 * @returns Promise resolving to full object ID
391
 */
392
function expandOid(args: {
393
  fs: FsClient;
394
  dir?: string;
395
  gitdir?: string;
396
  oid: string;
397
}): Promise<string>;
398
```
399

400
**Usage Example:**
401

402
```javascript
403
import git from "isomorphic-git";
404
import fs from "fs";
405

406
// Expand short SHA to full SHA
407
const fullSha = await git.expandOid({
408
  fs,
409
  dir: "/path/to/repo",
410
  oid: "abc123" // Short SHA
411
});
412
console.log("Full SHA:", fullSha); // Full 40-character SHA
413
```
414

415
## Types
416

417
```javascript { .api }
418
interface ReadObjectResult {
419
  oid: string;
420
  type: string;
421
  object: Uint8Array;
422
  format: string;
423
  source?: string;
424
}
425

426
interface ReadBlobResult {
427
  oid: string;
428
  blob: Uint8Array;
429
}
430

431
interface ReadTreeResult {
432
  oid: string;
433
  tree: TreeEntry[];
434
}
435

436
interface ReadTagResult {
437
  oid: string;
438
  tag: TagObject;
439
  payload: string;
440
}
441

442
interface TreeEntry {
443
  mode: string;
444
  path: string;
445
  oid: string;
446
  type: string;
447
}
448

449
interface TagObject {
450
  object: string;
451
  type: string;
452
  tag: string;
453
  message: string;
454
  tagger: PersonObject;
455
  gpgsig?: string;
456
}
457

458
interface PersonObject {
459
  name?: string;
460
  email?: string;
461
  timestamp?: number;
462
  timezoneOffset?: number;
463
}
464
```
465

466
## Working with Objects
467

468
### Create Files and Trees
469

470
```javascript
471
import git from "isomorphic-git";
472
import fs from "fs";
473

474
// Create blob from file content
475
const fileContent = new TextEncoder().encode("console.log('Hello, World!');");
476
const blobSha = await git.writeBlob({
477
  fs,
478
  dir: "/path/to/repo",
479
  blob: fileContent
480
});
481

482
// Create tree with the blob
483
const treeSha = await git.writeTree({
484
  fs,
485
  dir: "/path/to/repo",
486
  tree: [
487
    {
488
      mode: "100644",
489
      path: "index.js",
490
      oid: blobSha,
491
      type: "blob"
492
    }
493
  ]
494
});
495

496
console.log("Created blob:", blobSha);
497
console.log("Created tree:", treeSha);
498
```
499

500
### Read Object Contents
501

502
```javascript
503
import git from "isomorphic-git";
504
import fs from "fs";
505

506
// Read and display object contents
507
const object = await git.readObject({
508
  fs,
509
  dir: "/path/to/repo",
510
  oid: "object-sha-here",
511
  format: "parsed"
512
});
513

514
switch (object.type) {
515
  case "blob":
516
    console.log("File content:", new TextDecoder().decode(object.object));
517
    break;
518
  case "tree":
519
    console.log("Directory listing:", object.object);
520
    break;
521
  case "commit":
522
    console.log("Commit data:", object.object);
523
    break;
524
  case "tag":
525
    console.log("Tag data:", object.object);
526
    break;
527
}
528
```