0
# Remote Operations
1

2
Fetching, pushing, and managing remote repositories.
3

4
## Capabilities
5

6
### Fetch from Remote
7

8
Downloads objects and references from a remote repository.
9

10
```javascript { .api }
11
/**
12
 * Fetch updates from remote repository
13
 * @param args.fs - File system client
14
 * @param args.http - HTTP client
15
 * @param args.dir - Working tree directory path
16
 * @param args.gitdir - Git directory path
17
 * @param args.url - Remote repository URL
18
 * @param args.remote - Remote name (defaults to 'origin')
19
 * @param args.ref - Reference to fetch
20
 * @param args.remoteRef - Remote reference to fetch
21
 * @param args.depth - Shallow fetch depth
22
 * @param args.since - Only fetch commits after date
23
 * @param args.exclude - References to exclude
24
 * @param args.relative - Make depth relative to current
25
 * @param args.tags - Fetch tags
26
 * @param args.singleBranch - Only fetch single branch
27
 * @param args.headers - Additional HTTP headers
28
 * @param args.corsProxy - CORS proxy URL
29
 * @param args.onProgress - Progress callback
30
 * @param args.onMessage - Message callback
31
 * @param args.onAuth - Authentication callback
32
 * @param args.onAuthFailure - Auth failure callback
33
 * @param args.onAuthSuccess - Auth success callback
34
 * @param args.cache - Cache object
35
 * @returns Promise resolving to fetch result
36
 */
37
function fetch(args: {
38
  fs: FsClient;
39
  http: HttpClient;
40
  dir?: string;
41
  gitdir?: string;
42
  url?: string;
43
  remote?: string;
44
  ref?: string;
45
  remoteRef?: string;
46
  depth?: number;
47
  since?: Date;
48
  exclude?: string[];
49
  relative?: boolean;
50
  tags?: boolean;
51
  singleBranch?: boolean;
52
  headers?: Record<string, string>;
53
  corsProxy?: string;
54
  onProgress?: ProgressCallback;
55
  onMessage?: MessageCallback;
56
  onAuth?: AuthCallback;
57
  onAuthFailure?: AuthFailureCallback;
58
  onAuthSuccess?: AuthSuccessCallback;
59
  cache?: object;
60
}): Promise<FetchResult>;
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
import git from "isomorphic-git";
67
import http from "isomorphic-git/http/node";
68
import fs from "fs";
69

70
// Basic fetch from origin
71
const fetchResult = await git.fetch({
72
  fs,
73
  http,
74
  dir: "/path/to/repo",
75
  remote: "origin"
76
});
77
console.log("Fetch result:", fetchResult);
78

79
// Fetch specific branch
80
await git.fetch({
81
  fs,
82
  http,
83
  dir: "/path/to/repo",
84
  remote: "origin",
85
  ref: "main"
86
});
87

88
// Shallow fetch with progress tracking
89
await git.fetch({
90
  fs,
91
  http,
92
  dir: "/path/to/repo",
93
  remote: "origin",
94
  depth: 1,
95
  onProgress: (event) => {
96
    console.log(`Progress: ${event.phase} ${event.loaded}/${event.total}`);
97
  }
98
});
99

100
// Fetch with authentication
101
await git.fetch({
102
  fs,
103
  http,
104
  dir: "/path/to/repo",
105
  remote: "origin",
106
  onAuth: (url, auth) => {
107
    return {
108
      username: process.env.GIT_USERNAME,
109
      password: process.env.GIT_TOKEN
110
    };
111
  }
112
});
113
```
114

115
### Push to Remote
116

117
Uploads local commits to a remote repository.
118

119
```javascript { .api }
120
/**
121
 * Push changes to remote repository
122
 * @param args.fs - File system client
123
 * @param args.http - HTTP client
124
 * @param args.dir - Working tree directory path
125
 * @param args.gitdir - Git directory path
126
 * @param args.url - Remote repository URL
127
 * @param args.remote - Remote name (defaults to 'origin')
128
 * @param args.ref - Local reference to push
129
 * @param args.remoteRef - Remote reference to update
130
 * @param args.force - Force push (overwrite remote)
131
 * @param args.delete - Delete remote reference
132
 * @param args.corsProxy - CORS proxy URL
133
 * @param args.headers - Additional HTTP headers
134
 * @param args.onProgress - Progress callback
135
 * @param args.onMessage - Message callback
136
 * @param args.onAuth - Authentication callback
137
 * @param args.onAuthFailure - Auth failure callback
138
 * @param args.onAuthSuccess - Auth success callback
139
 * @returns Promise resolving to push result
140
 */
141
function push(args: {
142
  fs: FsClient;
143
  http: HttpClient;
144
  dir?: string;
145
  gitdir?: string;
146
  url?: string;
147
  remote?: string;
148
  ref?: string;
149
  remoteRef?: string;
150
  force?: boolean;
151
  delete?: boolean;
152
  corsProxy?: string;
153
  headers?: Record<string, string>;
154
  onProgress?: ProgressCallback;
155
  onMessage?: MessageCallback;
156
  onAuth?: AuthCallback;
157
  onAuthFailure?: AuthFailureCallback;
158
  onAuthSuccess?: AuthSuccessCallback;
159
}): Promise<PushResult>;
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
import git from "isomorphic-git";
166
import http from "isomorphic-git/http/node";
167
import fs from "fs";
168

169
// Basic push to origin
170
const pushResult = await git.push({
171
  fs,
172
  http,
173
  dir: "/path/to/repo",
174
  remote: "origin",
175
  ref: "main"
176
});
177
console.log("Push result:", pushResult);
178

179
// Push with authentication
180
await git.push({
181
  fs,
182
  http,
183
  dir: "/path/to/repo",
184
  remote: "origin", 
185
  ref: "feature-branch",
186
  onAuth: () => ({
187
    username: "your-username",
188
    password: "your-token"
189
  })
190
});
191

192
// Force push (dangerous!)
193
await git.push({
194
  fs,
195
  http,
196
  dir: "/path/to/repo",
197
  remote: "origin",
198
  ref: "main",
199
  force: true
200
});
201

202
// Push to different remote branch name
203
await git.push({
204
  fs,
205
  http,
206
  dir: "/path/to/repo",
207
  remote: "origin",
208
  ref: "local-branch",
209
  remoteRef: "remote-branch"
210
});
211
```
212

213
### Pull from Remote
214

215
Fetches and merges changes from a remote repository.
216

217
```javascript { .api }
218
/**
219
 * Pull changes from remote repository (fetch + merge)
220
 * @param args.fs - File system client
221
 * @param args.http - HTTP client
222
 * @param args.dir - Working tree directory path
223
 * @param args.gitdir - Git directory path
224
 * @param args.ref - Local branch to update
225
 * @param args.url - Remote repository URL
226
 * @param args.remote - Remote name
227
 * @param args.remoteRef - Remote branch to pull from
228
 * @param args.corsProxy - CORS proxy URL
229
 * @param args.headers - Additional HTTP headers
230
 * @param args.onProgress - Progress callback
231
 * @param args.onMessage - Message callback
232
 * @param args.onAuth - Authentication callback
233
 * @param args.onAuthFailure - Auth failure callback
234
 * @param args.onAuthSuccess - Auth success callback
235
 * @param args.fastForward - Only allow fast-forward merges
236
 * @param args.noUpdateBranch - Don't update branch pointer
237
 * @param args.cache - Cache object
238
 * @returns Promise resolving when pull completes
239
 */
240
function pull(args: {
241
  fs: FsClient;
242
  http: HttpClient;
243
  dir?: string;
244
  gitdir?: string;
245
  ref?: string;
246
  url?: string;
247
  remote?: string;
248
  remoteRef?: string;
249
  corsProxy?: string;
250
  headers?: Record<string, string>;
251
  onProgress?: ProgressCallback;
252
  onMessage?: MessageCallback;
253
  onAuth?: AuthCallback;
254
  onAuthFailure?: AuthFailureCallback;
255
  onAuthSuccess?: AuthSuccessCallback;
256
  fastForward?: boolean;
257
  noUpdateBranch?: boolean;
258
  cache?: object;
259
}): Promise<void>;
260
```
261

262
**Usage Examples:**
263

264
```javascript
265
import git from "isomorphic-git";
266
import http from "isomorphic-git/http/node";
267
import fs from "fs";
268

269
// Basic pull from origin/main into current branch
270
await git.pull({
271
  fs,
272
  http,
273
  dir: "/path/to/repo",
274
  remote: "origin",
275
  ref: "main"
276
});
277

278
// Pull with authentication and progress tracking
279
await git.pull({
280
  fs,
281
  http,
282
  dir: "/path/to/repo",
283
  remote: "origin",
284
  ref: "main",
285
  onAuth: () => ({
286
    username: process.env.GIT_USERNAME,
287
    password: process.env.GIT_TOKEN
288
  }),
289
  onProgress: (event) => {
290
    console.log(`${event.phase}: ${event.loaded}/${event.total}`);
291
  }
292
});
293

294
// Fast-forward only pull (fail if merge needed)
295
await git.pull({
296
  fs,
297
  http,
298
  dir: "/path/to/repo",
299
  remote: "origin",
300
  ref: "main",
301
  fastForward: true
302
});
303
```
304

305
### Add Remote
306

307
Adds a new remote repository.
308

309
```javascript { .api }
310
/**
311
 * Add a remote repository
312
 * @param args.fs - File system client
313
 * @param args.dir - Working tree directory path
314
 * @param args.gitdir - Git directory path
315
 * @param args.remote - Remote name
316
 * @param args.url - Remote repository URL
317
 * @param args.force - Overwrite existing remote
318
 * @returns Promise resolving when remote is added
319
 */
320
function addRemote(args: {
321
  fs: FsClient;
322
  dir?: string;
323
  gitdir?: string;
324
  remote: string;
325
  url: string;
326
  force?: boolean;
327
}): Promise<void>;
328
```
329

330
**Usage Examples:**
331

332
```javascript
333
import git from "isomorphic-git";
334
import fs from "fs";
335

336
// Add origin remote
337
await git.addRemote({
338
  fs,
339
  dir: "/path/to/repo",
340
  remote: "origin",
341
  url: "https://github.com/user/repo.git"
342
});
343

344
// Add upstream remote
345
await git.addRemote({
346
  fs,
347
  dir: "/path/to/repo",
348
  remote: "upstream",
349
  url: "https://github.com/original/repo.git"
350
});
351

352
// Force add remote (overwrite existing)
353
await git.addRemote({
354
  fs,
355
  dir: "/path/to/repo",
356
  remote: "origin",
357
  url: "https://github.com/user/new-repo.git",
358
  force: true
359
});
360
```
361

362
### List Remotes
363

364
Lists all configured remotes.
365

366
```javascript { .api }
367
/**
368
 * List remote repositories
369
 * @param args.fs - File system client
370
 * @param args.dir - Working tree directory path
371
 * @param args.gitdir - Git directory path
372
 * @returns Promise resolving to array of remote objects
373
 */
374
function listRemotes(args: {
375
  fs: FsClient;
376
  dir?: string;
377
  gitdir?: string;
378
}): Promise<RemoteDescription[]>;
379
```
380

381
**Usage Example:**
382

383
```javascript
384
import git from "isomorphic-git";
385
import fs from "fs";
386

387
const remotes = await git.listRemotes({
388
  fs,
389
  dir: "/path/to/repo"
390
});
391

392
for (const remote of remotes) {
393
  console.log(`${remote.remote}: ${remote.url}`);
394
}
395
// Output:
396
// origin: https://github.com/user/repo.git
397
// upstream: https://github.com/original/repo.git
398
```
399

400
### Delete Remote
401

402
Removes a remote repository configuration.
403

404
```javascript { .api }
405
/**
406
 * Delete a remote repository
407
 * @param args.fs - File system client
408
 * @param args.dir - Working tree directory path
409
 * @param args.gitdir - Git directory path
410
 * @param args.remote - Remote name to delete
411
 * @returns Promise resolving when remote is deleted
412
 */
413
function deleteRemote(args: {
414
  fs: FsClient;
415
  dir?: string;
416
  gitdir?: string;
417
  remote: string;
418
}): Promise<void>;
419
```
420

421
**Usage Example:**
422

423
```javascript
424
import git from "isomorphic-git";
425
import fs from "fs";
426

427
// Delete a remote
428
await git.deleteRemote({
429
  fs,
430
  dir: "/path/to/repo",
431
  remote: "old-remote"
432
});
433
```
434

435
### Get Remote Information
436

437
Gets detailed information about a remote repository.
438

439
```javascript { .api }
440
/**
441
 * Get information about a remote repository
442
 * @param args.http - HTTP client
443
 * @param args.url - Remote repository URL
444
 * @param args.corsProxy - CORS proxy URL
445
 * @param args.headers - Additional HTTP headers
446
 * @param args.onAuth - Authentication callback
447
 * @param args.onAuthFailure - Auth failure callback
448
 * @param args.onAuthSuccess - Auth success callback
449
 * @returns Promise resolving to remote info
450
 */
451
function getRemoteInfo(args: {
452
  http: HttpClient;
453
  url: string;
454
  corsProxy?: string;
455
  headers?: Record<string, string>;
456
  onAuth?: AuthCallback;
457
  onAuthFailure?: AuthFailureCallback;
458
  onAuthSuccess?: AuthSuccessCallback;
459
}): Promise<GetRemoteInfoResult>;
460

461
function getRemoteInfo2(args: {
462
  http: HttpClient;
463
  url: string;
464
  corsProxy?: string;
465
  headers?: Record<string, string>;
466
  onAuth?: AuthCallback;
467
  onAuthFailure?: AuthFailureCallback;
468
  onAuthSuccess?: AuthSuccessCallback;
469
}): Promise<GetRemoteInfoResult>;
470
```
471

472
**Usage Example:**
473

474
```javascript
475
import git from "isomorphic-git";
476
import http from "isomorphic-git/http/node";
477

478
const info = await git.getRemoteInfo({
479
  http,
480
  url: "https://github.com/user/repo.git"
481
});
482

483
console.log("Remote capabilities:", info.capabilities);
484
console.log("Default branch:", info.HEAD);
485
console.log("Available refs:", info.refs);
486
```
487

488
### List Server References
489

490
Lists all references available on a remote server.
491

492
```javascript { .api }
493
/**
494
 * List references on remote server
495
 * @param args.http - HTTP client
496
 * @param args.url - Remote repository URL
497
 * @param args.corsProxy - CORS proxy URL
498
 * @param args.headers - Additional HTTP headers
499
 * @param args.onAuth - Authentication callback
500
 * @param args.onAuthFailure - Auth failure callback
501
 * @param args.onAuthSuccess - Auth success callback
502
 * @returns Promise resolving to server refs
503
 */
504
function listServerRefs(args: {
505
  http: HttpClient;
506
  url: string;
507
  corsProxy?: string;
508
  headers?: Record<string, string>;
509
  onAuth?: AuthCallback;
510
  onAuthFailure?: AuthFailureCallback;
511
  onAuthSuccess?: AuthSuccessCallback;
512
}): Promise<ServerRef[]>;
513
```
514

515
**Usage Example:**
516

517
```javascript
518
import git from "isomorphic-git";
519
import http from "isomorphic-git/http/node";
520

521
const refs = await git.listServerRefs({
522
  http,
523
  url: "https://github.com/user/repo.git"
524
});
525

526
for (const ref of refs) {
527
  console.log(`${ref.ref}: ${ref.oid}`);
528
}
529
// Output:
530
// refs/heads/main: abc123...
531
// refs/heads/develop: def456...
532
// refs/tags/v1.0.0: ghi789...
533
```
534

535
## Types
536

537
```javascript { .api }
538
interface FetchResult {
539
  defaultBranch: string;
540
  fetchHead: string;
541
  fetchHeadDescription: string;
542
  headers: Record<string, string>;
543
  packfile?: string;
544
  progress?: any[];
545
}
546

547
interface PushResult {
548
  ok: string[];
549
  errors: string[];
550
  headers: Record<string, string>;
551
}
552

553
interface RemoteDescription {
554
  remote: string;
555
  url: string;
556
}
557

558
interface GetRemoteInfoResult {
559
  capabilities: string[];
560
  HEAD: string;
561
  refs: Record<string, string>;
562
}
563

564
interface ServerRef {
565
  ref: string;
566
  oid: string;
567
  target?: string;
568
  peeled?: string;
569
}
570

571
interface AuthResult {
572
  username?: string;
573
  password?: string;
574
  token?: string;
575
  oauth2format?: "github" | "bitbucket";
576
  headers?: Record<string, string>;
577
  cancel?: boolean;
578
}
579

580
interface AuthOptions {
581
  headers: Record<string, string>;
582
}
583
```