0
# isomorphic-git
1

2
isomorphic-git is a pure JavaScript reimplementation of Git that provides 100% interoperability with the canonical Git implementation. It works in both Node.js and browser environments without requiring native C++ modules, making it ideal for web applications and cross-platform JavaScript projects.
3

4
## Package Information
5

6
- **Package Name**: isomorphic-git
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install isomorphic-git`
10

11
## Core Imports
12

13
```javascript
14
import git from "isomorphic-git";
15
```
16

17
Named imports for tree-shaking:
18

19
```javascript
20
import { clone, add, commit, push, pull } from "isomorphic-git";
21
```
22

23
CommonJS:
24

25
```javascript
26
const git = require("isomorphic-git");
27
const { clone, add, commit } = require("isomorphic-git");
28
```
29

30
HTTP clients:
31

32
```javascript
33
// Node.js
34
import http from "isomorphic-git/http/node";
35

36
// Browser
37
import http from "isomorphic-git/http/web";
38
```
39

40
## Basic Usage
41

42
```javascript
43
import git from "isomorphic-git";
44
import http from "isomorphic-git/http/node";
45
import fs from "fs";
46

47
// Clone a repository
48
await git.clone({
49
  fs,
50
  http,
51
  dir: "/path/to/repo",
52
  url: "https://github.com/user/repo.git"
53
});
54

55
// Make changes and commit
56
await git.add({ fs, dir: "/path/to/repo", filepath: "file.txt" });
57
await git.commit({
58
  fs,
59
  dir: "/path/to/repo",
60
  message: "Add file.txt",
61
  author: {
62
    name: "Your Name",
63
    email: "you@example.com"
64
  }
65
});
66
```
67

68
## Architecture
69

70
isomorphic-git is built around several key design principles:
71

72
- **Isomorphic Design**: Same API works in Node.js and browsers by abstracting file system and HTTP operations
73
- **Modular Architecture**: Individual functions can be imported separately for smaller bundles
74
- **Pure JavaScript**: No native dependencies, works everywhere JavaScript runs
75
- **Git Compatibility**: Operates directly on standard `.git` directories for full interoperability
76
- **Plugin System**: Supports pluggable file systems and HTTP clients
77

78
## Capabilities
79

80
### Repository Management
81

82
Core operations for initializing, cloning, and managing Git repositories.
83

84
```javascript { .api }
85
function init(args: {
86
  fs: FsClient;
87
  dir?: string;
88
  gitdir?: string;
89
  bare?: boolean;
90
  defaultBranch?: string;
91
}): Promise<void>;
92

93
function clone(args: {
94
  fs: FsClient;
95
  http: HttpClient;
96
  dir: string;
97
  gitdir?: string;
98
  url: string;
99
  corsProxy?: string;
100
  ref?: string;
101
  singleBranch?: boolean;
102
  noCheckout?: boolean;
103
  noTags?: boolean;
104
  remote?: string;
105
  depth?: number;
106
  since?: Date;
107
  exclude?: string[];
108
  relative?: boolean;
109
  headers?: Record<string, string>;
110
  onProgress?: ProgressCallback;
111
  onMessage?: MessageCallback;
112
  onAuth?: AuthCallback;
113
  onAuthFailure?: AuthFailureCallback;
114
  onAuthSuccess?: AuthSuccessCallback;
115
  onPostCheckout?: PostCheckoutCallback;
116
  cache?: object;
117
  nonBlocking?: boolean;
118
  batchSize?: number;
119
}): Promise<void>;
120

121
function version(): string;
122
```
123

124
[Repository Operations](./repository-operations.md)
125

126
### Working Directory Operations
127

128
Functions for staging files, checking status, and managing the working directory.
129

130
```javascript { .api }
131
function add(args: {
132
  fs: FsClient;
133
  dir?: string;
134
  gitdir?: string;
135
  filepath: string | string[];
136
  cache?: object;
137
  force?: boolean;
138
  parallel?: boolean;
139
}): Promise<void>;
140

141
function remove(args: {
142
  fs: FsClient;
143
  dir?: string;
144
  gitdir?: string;
145
  filepath: string;
146
  cache?: object;
147
}): Promise<void>;
148

149
function status(args: {
150
  fs: FsClient;
151
  dir?: string;
152
  gitdir?: string;
153
  filepath: string;
154
  cache?: object;
155
}): Promise<'ignored' | 'unmodified' | '*modified' | '*deleted' | '*added' | 'absent' | 'modified' | 'deleted' | 'added' | '*unmodified' | '*absent' | '*undeleted' | '*undeletemodified'>;
156

157
function statusMatrix(args: {
158
  fs: FsClient;
159
  dir?: string;
160
  gitdir?: string;
161
  ref?: string;
162
  filepaths?: string[];
163
  filter?: (f: string) => boolean;
164
  cache?: object;
165
  ignored?: boolean;
166
}): Promise<Array<[string, number, number, number]>>;
167
```
168

169
[Working Directory](./working-directory.md)
170

171
### Commit Operations
172

173
Creating commits, reading commit history, and commit-related operations.
174

175
```javascript { .api }
176
function commit(args: {
177
  fs: FsClient;
178
  dir?: string;
179
  gitdir?: string;
180
  message?: string;
181
  author?: PersonObject;
182
  committer?: PersonObject;
183
  signingKey?: string;
184
  onSign?: SignCallback;
185
  amend?: boolean;
186
  dryRun?: boolean;
187
  noUpdateBranch?: boolean;
188
  ref?: string;
189
  parent?: string[];
190
  tree?: string;
191
  cache?: object;
192
}): Promise<string>;
193

194
function log(args: {
195
  fs: FsClient;
196
  dir?: string;
197
  gitdir?: string;
198
  ref?: string;
199
  depth?: number;
200
  since?: Date;
201
  until?: Date;
202
  force?: boolean;
203
  follow?: boolean;
204
  cache?: object;
205
}): Promise<ReadCommitResult[]>;
206
```
207

208
[Commit Operations](./commit-operations.md)
209

210
### Branch Management
211

212
Creating, switching, listing, and managing branches.
213

214
```javascript { .api }
215
function branch(args: {
216
  fs: FsClient;
217
  dir?: string;
218
  gitdir?: string;
219
  ref: string;
220
  object?: string;
221
  checkout?: boolean;
222
  force?: boolean;
223
}): Promise<void>;
224

225
function checkout(args: {
226
  fs: FsClient;
227
  dir?: string;
228
  gitdir?: string;
229
  ref: string;
230
  remote?: string;
231
  noCheckout?: boolean;
232
  force?: boolean;
233
  track?: boolean;
234
  filepaths?: string[];
235
  cache?: object;
236
  onProgress?: ProgressCallback;
237
}): Promise<void>;
238

239
function currentBranch(args: {
240
  fs: FsClient;
241
  dir?: string;
242
  gitdir?: string;
243
  fullname?: boolean;
244
}): Promise<string | undefined>;
245

246
function listBranches(args: {
247
  fs: FsClient;
248
  dir?: string;
249
  gitdir?: string;
250
  remote?: string;
251
}): Promise<string[]>;
252
```
253

254
[Branch Management](./branch-management.md)
255

256
### Remote Operations
257

258
Fetching, pushing, and managing remote repositories.
259

260
```javascript { .api }
261
function fetch(args: {
262
  fs: FsClient;
263
  http: HttpClient;
264
  dir?: string;
265
  gitdir?: string;
266
  url?: string;
267
  remote?: string;
268
  ref?: string;
269
  remoteRef?: string;
270
  depth?: number;
271
  since?: Date;
272
  exclude?: string[];
273
  relative?: boolean;
274
  tags?: boolean;
275
  singleBranch?: boolean;
276
  headers?: Record<string, string>;
277
  corsProxy?: string;
278
  onProgress?: ProgressCallback;
279
  onMessage?: MessageCallback;
280
  onAuth?: AuthCallback;
281
  onAuthFailure?: AuthFailureCallback;
282
  onAuthSuccess?: AuthSuccessCallback;
283
  cache?: object;
284
}): Promise<FetchResult>;
285

286
function push(args: {
287
  fs: FsClient;
288
  http: HttpClient;
289
  dir?: string;
290
  gitdir?: string;
291
  url?: string;
292
  remote?: string;
293
  ref?: string;
294
  remoteRef?: string;
295
  force?: boolean;
296
  delete?: boolean;
297
  corsProxy?: string;
298
  headers?: Record<string, string>;
299
  onProgress?: ProgressCallback;
300
  onMessage?: MessageCallback;
301
  onAuth?: AuthCallback;
302
  onAuthFailure?: AuthFailureCallback;
303
  onAuthSuccess?: AuthSuccessCallback;
304
}): Promise<PushResult>;
305

306
function pull(args: {
307
  fs: FsClient;
308
  http: HttpClient;
309
  dir?: string;
310
  gitdir?: string;
311
  ref?: string;
312
  url?: string;
313
  remote?: string;
314
  remoteRef?: string;
315
  corsProxy?: string;
316
  headers?: Record<string, string>;
317
  onProgress?: ProgressCallback;
318
  onMessage?: MessageCallback;
319
  onAuth?: AuthCallback;
320
  onAuthFailure?: AuthFailureCallback;
321
  onAuthSuccess?: AuthSuccessCallback;
322
  fastForward?: boolean;
323
  noUpdateBranch?: boolean;
324
  cache?: object;
325
}): Promise<void>;
326
```
327

328
[Remote Operations](./remote-operations.md)
329

330
### Configuration Management
331

332
Reading and writing Git configuration values.
333

334
```javascript { .api }
335
function getConfig(args: {
336
  fs: FsClient;
337
  dir?: string;
338
  gitdir?: string;
339
  path: string;
340
}): Promise<any>;
341

342
function getConfigAll(args: {
343
  fs: FsClient;
344
  dir?: string;
345
  gitdir?: string;
346
  path: string;
347
}): Promise<any[]>;
348

349
function setConfig(args: {
350
  fs: FsClient;
351
  dir?: string;
352
  gitdir?: string;
353
  path: string;
354
  value: any;
355
  append?: boolean;
356
}): Promise<void>;
357
```
358

359
[Configuration](./configuration.md)
360

361
### Object Operations
362

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

365
```javascript { .api }
366
function readObject(args: {
367
  fs: FsClient;
368
  dir?: string;
369
  gitdir?: string;
370
  oid: string;
371
  format?: string;
372
  filepath?: string;
373
  encoding?: string;
374
}): Promise<ReadObjectResult>;
375

376
function writeObject(args: {
377
  fs: FsClient;
378
  dir?: string;
379
  gitdir?: string;
380
  type: string;
381
  object: Uint8Array;
382
  format?: string;
383
  oid?: string;
384
  encoding?: string;
385
}): Promise<string>;
386

387
function hashBlob(args: {
388
  object: Uint8Array;
389
}): Promise<string>;
390
```
391

392
[Object Operations](./object-operations.md)
393

394
### Reference Management
395

396
Managing Git references (branches, tags, HEAD).
397

398
```javascript { .api }
399
function resolveRef(args: {
400
  fs: FsClient;
401
  dir?: string;
402
  gitdir?: string;
403
  ref: string;
404
  depth?: number;
405
}): Promise<string>;
406

407
function expandRef(args: {
408
  fs: FsClient;
409
  dir?: string;
410
  gitdir?: string;
411
  ref: string;
412
}): Promise<string>;
413

414
function listRefs(args: {
415
  fs: FsClient;
416
  dir?: string;
417
  gitdir?: string;
418
}): Promise<string[]>;
419

420
function writeRef(args: {
421
  fs: FsClient;
422
  dir?: string;
423
  gitdir?: string;
424
  ref: string;
425
  value: string;
426
  force?: boolean;
427
  symbolic?: boolean;
428
}): Promise<void>;
429
```
430

431
[Reference Management](./reference-management.md)
432

433
### Advanced Operations
434

435
Advanced Git operations including merging, rebasing, and repository walking.
436

437
```javascript { .api }
438
function merge(args: {
439
  fs: FsClient;
440
  dir?: string;
441
  gitdir?: string;
442
  ours?: string;
443
  theirs: string;
444
  fastForward?: boolean;
445
  noUpdateBranch?: boolean;
446
  dryRun?: boolean;
447
  abortOnConflict?: boolean;
448
  message?: string;
449
  author?: PersonObject;
450
  committer?: PersonObject;
451
  signingKey?: string;
452
  onSign?: SignCallback;
453
  cache?: object;
454
}): Promise<MergeResult>;
455

456
function walk(args: {
457
  fs: FsClient;
458
  dir?: string;
459
  gitdir?: string;
460
  trees: Walker[];
461
  map?: (filepath: string, entries: WalkerEntry[]) => any;
462
  reduce?: (parent: any, children: any[]) => any;
463
  iterate?: (entries: WalkerEntry[], children: any[]) => any;
464
  cache?: object;
465
}): Promise<any>;
466
```
467

468
[Advanced Operations](./advanced-operations.md)
469

470
## Types
471

472
```javascript { .api }
473
interface FsClient {
474
  promises: {
475
    readFile(filepath: string, options?: any): Promise<Buffer | string>;
476
    writeFile(filepath: string, data: any, options?: any): Promise<void>;
477
    mkdir(dir: string, options?: any): Promise<void>;
478
    rmdir(dir: string, options?: any): Promise<void>;
479
    unlink(filepath: string): Promise<void>;
480
    stat(filepath: string): Promise<Stats>;
481
    lstat(filepath: string): Promise<Stats>;
482
    readdir(dir: string): Promise<string[]>;
483
    readlink(filepath: string): Promise<string>;
484
    symlink(target: string, filepath: string): Promise<void>;
485
    chmod(filepath: string, mode: number): Promise<void>;
486
  };
487
}
488

489
interface HttpClient {
490
  request(args: GitHttpRequest): Promise<GitHttpResponse>;
491
}
492

493
interface PersonObject {
494
  name?: string;
495
  email?: string;
496
  timestamp?: number;
497
  timezoneOffset?: number;
498
}
499

500
interface GitHttpRequest {
501
  url: string;
502
  method?: string;
503
  headers?: Record<string, string>;
504
  body?: Uint8Array | AsyncIterable<Uint8Array>;
505
  onProgress?: ProgressCallback;
506
  agent?: any;
507
}
508

509
interface GitHttpResponse {
510
  url: string;
511
  method?: string;
512
  statusCode: number;
513
  statusMessage: string;
514
  body: AsyncIterable<Uint8Array>;
515
  headers: Record<string, string>;
516
}
517

518
type ProgressCallback = (progress: ProgressEvent) => void | Promise<void>;
519
type MessageCallback = (message: string) => void | Promise<void>;
520
type AuthCallback = (url: string, auth: AuthOptions) => AuthResult | Promise<AuthResult>;
521
type AuthFailureCallback = (url: string, auth: AuthOptions) => void | Promise<void>;
522
type AuthSuccessCallback = (url: string, auth: AuthOptions) => void | Promise<void>;
523
type PostCheckoutCallback = () => void | Promise<void>;
524
type SignCallback = (args: SignArgs) => string | Promise<string>;
525

526
// Walker constants for repository traversal
527
const STAGE: Walker;  // Git index walker
528
const TREE: Walker;   // Git tree walker  
529
const WORKDIR: Walker; // Working directory walker
530
```
531

532
## Error Handling
533

534
isomorphic-git provides a comprehensive set of error classes for different failure conditions:
535

536
```javascript { .api }
537
// Import all error classes
538
import { Errors } from "isomorphic-git";
539

540
// Common error types
541
class NotFoundError extends Error {}
542
class InvalidRefNameError extends Error {}
543
class CheckoutConflictError extends Error {}
544
class MergeConflictError extends Error {}
545
class PushRejectedError extends Error {}
546
class HttpError extends Error {}
547
class GitPushError extends Error {}
548
```
549

550
[Error Handling](./error-handling.md)
551

552
## CLI Tool
553

554
isomorphic-git includes a command-line interface for testing and basic operations:
555

556
```bash
557
# Install globally
558
npm install -g isomorphic-git
559

560
# Use the isogit command
561
isogit clone https://github.com/user/repo.git ./repo
562
isogit status --dir ./repo
563
isogit log --dir ./repo
564
```
565

566
## Browser Considerations
567

568
When using isomorphic-git in browsers:
569

570
- Use `isomorphic-git/http/web` for HTTP client
571
- Provide a compatible file system like [LightningFS](https://github.com/isomorphic-git/lightning-fs)
572
- Use CORS proxy for cross-origin requests: `corsProxy: "https://cors.isomorphic-git.org"`
573
- Consider using service workers for background operations