0
# Remote Operations
1

2
Remote repository operations including fetching, pushing, and managing remote connections. Remote operations enable synchronization with other Git repositories over various protocols including HTTP, SSH, and local filesystem.
3

4
## Capabilities
5

6
### Remote Management
7

8
Create, configure, and manage remote repositories.
9

10
```javascript { .api }
11
/**
12
 * Create new remote
13
 * @param {Repository} repo - Repository instance
14
 * @param {string} name - Remote name (e.g., "origin")
15
 * @param {string} url - Remote URL
16
 * @returns {Promise<Remote>} New remote
17
 */
18
Remote.create(repo, name, url): Promise<Remote>;
19

20
/**
21
 * Create anonymous remote (temporary)
22
 * @param {Repository} repo - Repository instance
23
 * @param {string} url - Remote URL
24
 * @returns {Promise<Remote>} Anonymous remote
25
 */
26
Remote.createAnonymous(repo, url): Promise<Remote>;
27

28
/**
29
 * Create remote with fetch refspec
30
 * @param {Repository} repo - Repository instance
31
 * @param {string} name - Remote name
32
 * @param {string} url - Remote URL
33
 * @param {string} fetch - Fetch refspec
34
 * @returns {Promise<Remote>} New remote with refspec
35
 */
36
Remote.createWithFetchspec(repo, name, url, fetch): Promise<Remote>;
37

38
/**
39
 * Look up remote by name
40
 * @param {Repository} repo - Repository instance
41
 * @param {string} name - Remote name
42
 * @returns {Promise<Remote>} Remote object
43
 */
44
Remote.lookup(repo, name): Promise<Remote>;
45

46
/**
47
 * List all remotes
48
 * @param {Repository} repo - Repository instance
49
 * @returns {Promise<string[]>} Array of remote names
50
 */
51
Remote.list(repo): Promise<string[]>;
52

53
/**
54
 * Delete remote
55
 * @param {Repository} repo - Repository instance
56
 * @param {string} name - Remote name to delete
57
 * @returns {Promise<void>}
58
 */
59
Remote.delete(repo, name): Promise<void>;
60

61
/**
62
 * Rename remote
63
 * @param {Repository} repo - Repository instance
64
 * @param {string} name - Current remote name
65
 * @param {string} newName - New remote name
66
 * @returns {Promise<string[]>} Array of problems encountered
67
 */
68
Remote.rename(repo, name, newName): Promise<string[]>;
69

70
/**
71
 * Validate remote name
72
 * @param {string} remoteName - Remote name to validate
73
 * @returns {boolean} True if valid
74
 */
75
Remote.isValidName(remoteName): boolean;
76
```
77

78
**Usage Examples:**
79

80
```javascript
81
const NodeGit = require('nodegit');
82

83
const repo = await NodeGit.Repository.open('./my-repo');
84

85
// Create new remote
86
const remote = await NodeGit.Remote.create(
87
  repo,
88
  'upstream',
89
  'https://github.com/original/repo.git'
90
);
91

92
// Look up existing remote
93
const origin = await NodeGit.Remote.lookup(repo, 'origin');
94
console.log('Origin URL:', origin.url());
95

96
// List all remotes
97
const remotes = await NodeGit.Remote.list(repo);
98
remotes.forEach(function(remoteName) {
99
  console.log('Remote:', remoteName);
100
});
101

102
// Validate remote name
103
if (NodeGit.Remote.isValidName('my-remote')) {
104
  console.log('Valid remote name');
105
}
106

107
// Rename remote
108
const problems = await NodeGit.Remote.rename(repo, 'origin', 'old-origin');
109
if (problems.length > 0) {
110
  console.log('Rename problems:', problems);
111
}
112
```
113

114
### Remote Configuration
115

116
Configure remote properties and refspecs.
117

118
```javascript { .api }
119
/**
120
 * Set remote URL
121
 * @param {Repository} repo - Repository instance
122
 * @param {string} remote - Remote name
123
 * @param {string} url - New URL
124
 * @returns {Promise<void>}
125
 */
126
Remote.setUrl(repo, remote, url): Promise<void>;
127

128
/**
129
 * Set push refspecs
130
 * @param {Repository} repo - Repository instance
131
 * @param {string} remote - Remote name
132
 * @param {string[]} array - Array of refspecs
133
 * @returns {Promise<void>}
134
 */
135
Remote.setPushRefspecs(repo, remote, array): Promise<void>;
136

137
/**
138
 * Set autotag behavior
139
 * @param {Repository} repo - Repository instance
140
 * @param {string} remote - Remote name
141
 * @param {number} value - Autotag value
142
 * @returns {Promise<void>}
143
 */
144
Remote.setAutotag(repo, remote, value): Promise<void>;
145
```
146

147
### Remote Instance Methods
148

149
Methods available on Remote objects.
150

151
```javascript { .api }
152
/**
153
 * Get remote name
154
 * @returns {string} Remote name
155
 */
156
remote.name(): string;
157

158
/**
159
 * Get remote URL
160
 * @returns {string} Remote URL
161
 */
162
remote.url(): string;
163

164
/**
165
 * Get owning repository
166
 * @returns {Repository} Repository instance
167
 */
168
remote.owner(): Repository;
169

170
/**
171
 * Get autotag setting
172
 * @returns {number} Autotag setting
173
 */
174
remote.autotag(): number;
175

176
/**
177
 * Get fetch refspecs
178
 * @returns {Promise<string[]>} Array of fetch refspecs
179
 */
180
remote.getFetchRefspecs(): Promise<string[]>;
181

182
/**
183
 * Get push refspecs
184
 * @returns {Promise<string[]>} Array of push refspecs
185
 */
186
remote.getPushRefspecs(): Promise<string[]>;
187

188
/**
189
 * Get refspec count
190
 * @returns {number} Number of refspecs
191
 */
192
remote.refspecCount(): number;
193

194
/**
195
 * Duplicate remote
196
 * @returns {Promise<Remote>} Duplicated remote
197
 */
198
remote.dup(): Promise<Remote>;
199
```
200

201
**Usage Examples:**
202

203
```javascript
204
const remote = await NodeGit.Remote.lookup(repo, 'origin');
205

206
// Get remote information
207
console.log('Remote name:', remote.name());
208
console.log('Remote URL:', remote.url());
209
console.log('Autotag setting:', remote.autotag());
210

211
// Get refspecs
212
const fetchSpecs = await remote.getFetchRefspecs();
213
const pushSpecs = await remote.getPushRefspecs();
214

215
console.log('Fetch refspecs:', fetchSpecs);
216
console.log('Push refspecs:', pushSpecs);
217

218
// Configure remote
219
await NodeGit.Remote.setUrl(repo, 'origin', 'git@github.com:user/repo.git');
220
```
221

222
### Remote Connection
223

224
Connect to and communicate with remotes.
225

226
```javascript { .api }
227
/**
228
 * Connect to remote
229
 * @param {number} direction - Connection direction (FETCH or PUSH)
230
 * @param {RemoteCallbacks} callbacks - Remote callbacks
231
 * @returns {Promise<void>}
232
 */
233
remote.connect(direction, callbacks): Promise<void>;
234

235
/**
236
 * Check if remote is connected
237
 * @returns {boolean} True if connected
238
 */
239
remote.connected(): boolean;
240

241
/**
242
 * Disconnect from remote
243
 * @returns {Promise<void>}
244
 */
245
remote.disconnect(): Promise<void>;
246

247
/**
248
 * Stop remote operation
249
 * @returns {Promise<void>}
250
 */
251
remote.stop(): Promise<void>;
252

253
/**
254
 * Get default branch
255
 * @returns {Promise<string>} Default branch name
256
 */
257
remote.defaultBranch(): Promise<string>;
258

259
/**
260
 * List remote references
261
 * @returns {Promise<RemoteHead[]>} Array of remote references
262
 */
263
remote.ls(): Promise<RemoteHead[]>;
264
```
265

266
### Fetch Operations
267

268
Download objects and references from remote repositories.
269

270
```javascript { .api }
271
/**
272
 * Fetch from remote
273
 * @param {string[]} refspecs - Refspecs to fetch (optional)
274
 * @param {FetchOptions} opts - Fetch options
275
 * @param {string} message - Reflog message
276
 * @returns {Promise<void>}
277
 */
278
remote.fetch(refspecs, opts, message): Promise<void>;
279

280
/**
281
 * Download from remote (without updating references)
282
 * @param {string[]} refspecs - Refspecs to download
283
 * @param {FetchOptions} opts - Download options
284
 * @returns {Promise<void>}
285
 */
286
remote.download(refspecs, opts): Promise<void>;
287

288
/**
289
 * Update tips after fetch
290
 * @param {RemoteCallbacks} callbacks - Update callbacks
291
 * @param {boolean} updateFetchhead - Update FETCH_HEAD
292
 * @param {number} downloadTags - Tag download mode
293
 * @param {string} reflogMessage - Reflog message
294
 * @returns {Promise<void>}
295
 */
296
remote.updateTips(callbacks, updateFetchhead, downloadTags, reflogMessage): Promise<void>;
297

298
/**
299
 * Get transfer statistics
300
 * @returns {TransferProgress} Transfer statistics
301
 */
302
remote.stats(): TransferProgress;
303
```
304

305
**Usage Examples:**
306

307
```javascript
308
// Set up callbacks for authentication
309
const fetchCallbacks = {
310
  credentials: function(url, userName) {
311
    // Return credentials for authentication
312
    return NodeGit.Cred.sshKeyFromAgent(userName);
313
  },
314
  certificateCheck: function() {
315
    return 0; // Accept all certificates
316
  },
317
  transferProgress: function(stats) {
318
    console.log('Progress:', stats.receivedObjects(), '/', stats.totalObjects());
319
  }
320
};
321

322
// Connect and fetch
323
const remote = await NodeGit.Remote.lookup(repo, 'origin');
324

325
await remote.connect(NodeGit.Enums.DIRECTION.FETCH, fetchCallbacks);
326

327
console.log('Connected to:', remote.url());
328
console.log('Default branch:', await remote.defaultBranch());
329

330
// List remote references
331
const refs = await remote.ls();
332
refs.forEach(function(ref) {
333
  console.log('Remote ref:', ref.name(), ref.oid().tostrS());
334
});
335

336
// Fetch all references
337
await remote.fetch(null, {
338
  callbacks: fetchCallbacks
339
}, 'fetch from origin');
340

341
// Get transfer stats
342
const stats = remote.stats();
343
console.log('Received objects:', stats.receivedObjects());
344

345
await remote.disconnect();
346
```
347

348
### Push Operations
349

350
Upload objects and references to remote repositories.
351

352
```javascript { .api }
353
/**
354
 * Push to remote
355
 * @param {string[]} refSpecs - Refspecs to push
356
 * @param {PushOptions} options - Push options
357
 * @returns {Promise<void>}
358
 */
359
remote.push(refSpecs, options): Promise<void>;
360

361
/**
362
 * Upload to remote (without updating references)
363
 * @param {string[]} refspecs - Refspecs to upload
364
 * @param {PushOptions} opts - Upload options
365
 * @returns {Promise<void>}
366
 */
367
remote.upload(refspecs, opts): Promise<void>;
368
```
369

370
**Usage Examples:**
371

372
```javascript
373
// Set up push callbacks
374
const pushCallbacks = {
375
  credentials: function(url, userName) {
376
    return NodeGit.Cred.sshKeyFromAgent(userName);
377
  },
378
  pushTransferProgress: function(current, total, bytes) {
379
    console.log('Push progress:', current, '/', total, 'bytes:', bytes);
380
  },
381
  pushUpdateReference: function(refname, status) {
382
    if (status) {
383
      console.log('Failed to push', refname, 'with status:', status);
384
    } else {
385
      console.log('Successfully pushed', refname);
386
    }
387
  }
388
};
389

390
// Push branch to remote
391
const remote = await NodeGit.Remote.lookup(repo, 'origin');
392

393
await remote.push(
394
  ['refs/heads/main:refs/heads/main'],
395
  {
396
    callbacks: pushCallbacks
397
  }
398
);
399

400
console.log('Push completed');
401
```
402

403
### Repository Remote Methods
404

405
Convenience methods on Repository for remote operations.
406

407
```javascript { .api }
408
/**
409
 * Get remote by name
410
 * @param {string} name - Remote name
411
 * @returns {Promise<Remote>} Remote object
412
 */
413
repository.getRemote(name): Promise<Remote>;
414

415
/**
416
 * Get all remotes
417
 * @returns {Promise<string[]>} Array of remote names
418
 */
419
repository.getRemotes(): Promise<string[]>;
420

421
/**
422
 * Create remote
423
 * @param {string} name - Remote name
424
 * @param {string} url - Remote URL
425
 * @returns {Promise<Remote>} New remote
426
 */
427
repository.createRemote(name, url): Promise<Remote>;
428

429
/**
430
 * Fetch from remote
431
 * @param {string} remote - Remote name
432
 * @param {FetchOptions} opts - Fetch options
433
 * @returns {Promise<void>}
434
 */
435
repository.fetch(remote, opts): Promise<void>;
436

437
/**
438
 * Fetch from all remotes
439
 * @param {FetchOptions} opts - Fetch options
440
 * @returns {Promise<void>}
441
 */
442
repository.fetchAll(opts): Promise<void>;
443
```
444

445
### Remote Pruning
446

447
Clean up stale remote references.
448

449
```javascript { .api }
450
/**
451
 * Prune remote references
452
 * @param {RemoteCallbacks} callbacks - Prune callbacks
453
 * @returns {Promise<void>}
454
 */
455
remote.prune(callbacks): Promise<void>;
456

457
/**
458
 * Get references that would be pruned
459
 * @returns {Promise<string[]>} Array of reference names
460
 */
461
remote.pruneRefs(): Promise<string[]>;
462
```
463

464
**Usage Examples:**
465

466
```javascript
467
// Repository-level remote operations
468
const remotes = await repo.getRemotes();
469
console.log('Remotes:', remotes);
470

471
// Fetch from specific remote
472
await repo.fetch('origin', {
473
  callbacks: {
474
    credentials: function(url, userName) {
475
      return NodeGit.Cred.sshKeyFromAgent(userName);
476
    }
477
  }
478
});
479

480
// Fetch from all remotes
481
await repo.fetchAll({
482
  callbacks: {
483
    credentials: function(url, userName) {
484
      return NodeGit.Cred.sshKeyFromAgent(userName);
485
    }
486
  }
487
});
488

489
// Prune stale references
490
const remote = await repo.getRemote('origin');
491
const staleBranches = await remote.pruneRefs();
492
console.log('Stale branches:', staleBranches);
493

494
await remote.prune({
495
  credentials: function(url, userName) {
496
    return NodeGit.Cred.sshKeyFromAgent(userName);
497
  }
498
});
499
```
500

501
### Clone Operations
502

503
Clone remote repositories locally.
504

505
```javascript { .api }
506
/**
507
 * Clone repository
508
 * @param {string} url - URL of remote repository
509
 * @param {string} localPath - Local path to clone to
510
 * @param {CloneOptions} options - Clone options
511
 * @returns {Promise<Repository>} Cloned repository
512
 */
513
Clone.clone(url, localPath, options): Promise<Repository>;
514
```
515

516
**Usage Examples:**
517

518
```javascript
519
// Clone with authentication
520
const cloneOptions = {
521
  fetchOpts: {
522
    callbacks: {
523
      certificateCheck: function() {
524
        return 0;
525
      },
526
      credentials: function(url, userName) {
527
        return NodeGit.Cred.sshKeyFromAgent(userName);
528
      },
529
      transferProgress: function(stats) {
530
        console.log('Clone progress:', 
531
          stats.receivedObjects(), '/', stats.totalObjects());
532
      }
533
    }
534
  },
535
  checkoutBranch: 'main'
536
};
537

538
const clonedRepo = await NodeGit.Clone.clone(
539
  'git@github.com:user/repo.git',
540
  './cloned-repo',
541
  cloneOptions
542
);
543

544
console.log('Repository cloned to:', clonedRepo.workdir());
545
```
546

547
## Types
548

549
```javascript { .api }
550
interface FetchOptions {
551
  callbacks: RemoteCallbacks;
552
  proxyOpts: ProxyOptions;
553
  downloadTags: number;
554
  customHeaders: string[];
555
}
556

557
interface PushOptions {
558
  callbacks: RemoteCallbacks;
559
  proxyOpts: ProxyOptions;
560
  customHeaders: string[];
561
}
562

563
interface RemoteCallbacks {
564
  credentials: Function;
565
  certificateCheck: Function;
566
  transferProgress: Function;
567
  updateTips: Function;
568
  packProgress: Function;
569
  pushTransferProgress: Function;
570
  pushUpdateReference: Function;
571
  sideband: Function;
572
}
573

574
interface ProxyOptions {
575
  type: number;
576
  url: string;
577
  credentials: Function;
578
  certificateCheck: Function;
579
}
580

581
interface CloneOptions {
582
  checkoutBranch: string;
583
  fetchOpts: FetchOptions;
584
  bare: boolean;
585
  localPath: string;
586
  repositoryCallback: Function;
587
  remoteCallback: Function;
588
}
589

590
interface TransferProgress {
591
  totalObjects(): number;
592
  indexedObjects(): number;
593
  receivedObjects(): number;
594
  localObjects(): number;
595
  totalDeltas(): number;
596
  indexedDeltas(): number;
597
  receivedBytes(): number;
598
}
599

600
interface RemoteHead {
601
  name(): string;
602
  oid(): Oid;
603
  loid(): Oid;
604
  local(): boolean;
605
}
606

607
// Direction constants
608
Enums.DIRECTION = {
609
  FETCH: 0,
610
  PUSH: 1
611
};
612

613
// Autotag constants
614
Remote.AUTOTAG_OPTION = {
615
  DOWNLOAD_TAGS_UNSPECIFIED: 0,
616
  DOWNLOAD_TAGS_AUTO: 1,
617
  DOWNLOAD_TAGS_NONE: 2,
618
  DOWNLOAD_TAGS_ALL: 3
619
};
620
```