0
# NodeGit
1

2
NodeGit is a comprehensive Node.js library that provides asynchronous native bindings to libgit2, enabling JavaScript applications to perform advanced Git operations programmatically. It offers a complete API for repository management including cloning, committing, branching, merging, and status tracking, along with low-level Git object manipulation capabilities for blobs, trees, and commits.
3

4
## Package Information
5

6
- **Package Name**: nodegit
7
- **Package Type**: npm  
8
- **Language**: JavaScript (with C++ native bindings)
9
- **Installation**: `npm install nodegit`
10

11
## Core Imports
12

13
```javascript
14
const NodeGit = require('nodegit');
15

16
// Core repository and object classes
17
const Repository = NodeGit.Repository;
18
const Commit = NodeGit.Commit;
19
const Tree = NodeGit.Tree;
20
const Blob = NodeGit.Blob;
21
const Tag = NodeGit.Tag;
22

23
// Repository operations
24
const Clone = NodeGit.Clone;
25
const Branch = NodeGit.Branch;
26
const Reference = NodeGit.Reference;
27
const Remote = NodeGit.Remote;
28
const Index = NodeGit.Index;
29

30
// Advanced operations
31
const Merge = NodeGit.Merge;
32
const Rebase = NodeGit.Rebase;
33
const Stash = NodeGit.Stash;
34
const Diff = NodeGit.Diff;
35
const Status = NodeGit.Status;
36

37
// Utility classes
38
const Blame = NodeGit.Blame;
39
const Revwalk = NodeGit.Revwalk;
40
const Config = NodeGit.Config;
41
const Signature = NodeGit.Signature;
42
const Checkout = NodeGit.Checkout;
43
```
44

45
CommonJS destructuring:
46

47
```javascript
48
const { 
49
  Repository, Clone, Commit, Tree, Blob, Tag,
50
  Branch, Reference, Remote, Index, Status, Diff,
51
  Merge, Rebase, Stash, Cherrypick, Revert,
52
  Blame, Revwalk, Config, Signature, Checkout
53
} = require('nodegit');
54
```
55

56
ES6 import (if using Babel/transpiler):
57

58
```javascript
59
import NodeGit from 'nodegit';
60
const { Repository, Commit, Clone } = NodeGit;
61
```
62

63
## Basic Usage
64

65
```javascript
66
const NodeGit = require('nodegit');
67

68
// Clone a repository
69
NodeGit.Clone('https://github.com/user/repo.git', './local-repo')
70
  .then(function(repository) {
71
    // Repository cloned successfully
72
    return repository.getHeadCommit();
73
  })
74
  .then(function(commit) {
75
    console.log('Latest commit:', commit.sha());
76
    console.log('Message:', commit.message());
77
  });
78

79
// Open existing repository
80
NodeGit.Repository.open('./path/to/repo')
81
  .then(function(repo) {
82
    // Get current branch
83
    return repo.getCurrentBranch();
84
  })
85
  .then(function(reference) {
86
    console.log('Current branch:', reference.shorthand());
87
  });
88
```
89

90
## Architecture
91

92
NodeGit is built using a 3-layer architecture:
93

94
- **Native C++ Layer**: Direct bindings to libgit2 C library for Git operations
95
- **Generated JavaScript Layer**: Auto-generated Promise wrappers that convert C++ callbacks to JavaScript Promises
96
- **Manual Extensions**: Hand-written JavaScript enhancements that add convenience methods and better developer experience
97
- **Repository Context**: Most operations require a Repository instance as the central context for Git operations
98

99
## Capabilities
100

101
### Repository Management
102

103
Core repository operations including initialization, opening, cloning, and configuration. The Repository class serves as the central hub for all Git operations.
104

105
```javascript { .api }
106
class Repository {
107
  static discover(path, acrossFs, ceilingDirs): Promise<string>;
108
  static init(path, opts): Promise<Repository>;
109
  static open(path): Promise<Repository>;
110
  static clone(url, localPath, options): Promise<Repository>;
111
  
112
  config(): Promise<Config>;
113
  head(): Promise<Reference>;
114
  index(): Promise<Index>;
115
  workdir(): string;
116
  getHeadCommit(): Promise<Commit>;
117
  getCurrentBranch(): Promise<Reference>;
118
  getStatus(): Promise<StatusFile[]>;
119
}
120
```
121

122
[Repository Management](./repository.md)
123

124
### Git Object Model  
125

126
Access to core Git objects including commits, trees, blobs, and tags. These classes provide full access to Git's object database.
127

128
```javascript { .api }
129
class Commit {
130
  static lookup(repo, oid): Promise<Commit>;
131
  static create(repo, updateRef, author, committer, encoding, message, tree, parentCount, parents): Promise<Oid>;
132
  
133
  id(): Oid;
134
  message(): string;
135
  author(): Signature;
136
  committer(): Signature;
137
  tree(): Promise<Tree>;
138
  getParents(): Promise<Commit[]>;
139
  sha(): string;
140
}
141

142
class Tree {
143
  static lookup(repo, oid): Promise<Tree>;
144
  
145
  id(): Oid;
146
  entries(): TreeEntry[];
147
  entryByPath(path): TreeEntry;
148
  diff(tree): Promise<Diff>;
149
}
150

151
class Blob {
152
  static lookup(repo, oid): Promise<Blob>;
153
  static createFromBuffer(repo, buffer): Promise<Oid>;
154
  
155
  id(): Oid;
156
  content(): Buffer;
157
  toString(): string;
158
  rawsize(): number;
159
}
160
```
161

162
[Git Objects](./objects.md)
163

164
### Index and Staging
165

166
Index operations for staging changes, managing the Git index, and preparing commits.
167

168
```javascript { .api }
169
class Index {
170
  static open(indexPath): Promise<Index>;
171
  
172
  add(pathspec): Promise<void>;
173
  addByPath(path): Promise<void>;
174
  entries(): IndexEntry[];
175
  write(): Promise<void>;
176
  writeTree(): Promise<Oid>;
177
}
178
```
179

180
[Index Operations](./index-operations.md)
181

182
### References and Branches
183

184
Branch and reference management including creation, deletion, and traversal of Git references.
185

186
```javascript { .api }
187
class Reference {
188
  static create(repo, name, oid, force, logMessage): Promise<Reference>;
189
  static lookup(repo, name): Promise<Reference>;
190
  static list(repo): Promise<string[]>;
191
  
192
  name(): string;
193
  shorthand(): string;
194
  target(): Oid;
195
  isBranch(): boolean;
196
  isRemote(): boolean;
197
}
198

199
class Branch {
200
  static create(repo, branchName, target, force): Promise<Reference>;
201
  static lookup(repo, branchName, branchType): Promise<Reference>;
202
  static delete(branch): Promise<void>;
203
}
204
```
205

206
[References and Branches](./references.md)
207

208
### Remote Operations
209

210
Remote repository operations including fetching, pushing, and managing remote connections.
211

212
```javascript { .api }
213
class Remote {
214
  static create(repo, name, url): Promise<Remote>;
215
  static lookup(repo, name): Promise<Remote>;
216
  
217
  connect(direction, callbacks): Promise<void>;
218
  fetch(refspecs, opts, message): Promise<void>;
219
  push(refSpecs, options): Promise<void>;
220
  name(): string;
221
  url(): string;
222
}
223

224
class Clone {
225
  static clone(url, localPath, options): Promise<Repository>;
226
}
227
```
228

229
[Remote Operations](./remotes.md)
230

231
### Diff and Status
232

233
File difference computation and working directory status tracking.
234

235
```javascript { .api }
236
class Diff {
237
  static treeToTree(repo, oldTree, newTree, opts): Promise<Diff>;
238
  static indexToWorkdir(repo, index, opts): Promise<Diff>;
239
  
240
  patches(): Promise<ConvenientPatch[]>;
241
  numDeltas(): number;
242
}
243

244
class Status {
245
  static file(repo, path): Promise<number>;
246
  static foreach(repo, callback): Promise<void>;
247
}
248
```
249

250
[Diff and Status](./diff-status.md)
251

252
### Advanced Operations
253

254
Complex Git workflows including merging, rebasing, stashing, and cherry-picking.
255

256
```javascript { .api }
257
class Merge {
258
  static commits(repo, ourCommit, theirCommit, opts): Promise<Index>;
259
  static base(repo, one, two): Promise<Oid>;
260
}
261

262
class Rebase {
263
  static init(repo, branch, upstream, onto, opts): Promise<Rebase>;
264
  
265
  next(): Promise<RebaseOperation>;
266
  commit(author, committer): Promise<Oid>;
267
  finish(signature): Promise<void>;
268
}
269

270
class Stash {
271
  static save(repo, stasher, message, flags): Promise<Oid>;
272
  static apply(repo, index, opts): Promise<void>;
273
  static drop(repo, index): Promise<void>;
274
}
275
```
276

277
[Advanced Operations](./advanced.md)
278

279
### Blame and History
280

281
File annotation and history tracking for determining line-by-line changes and commit traversal.
282

283
```javascript { .api }
284
class Blame {
285
  static file(repo, path, options): Promise<Blame>;
286
  
287
  getHunkCount(): number;
288
  getHunkByIndex(index): BlameHunk;
289
  getHunkByLine(lineNumber): BlameHunk;
290
}
291

292
class Revwalk {
293
  static create(repo): Revwalk;
294
  
295
  sorting(...sorts): void;
296
  push(oid): void;
297
  pushHead(): void;
298
  next(): Promise<Oid>;
299
  getCommits(count): Promise<Commit[]>;
300
  getCommitsUntil(checkFn): Promise<Commit[]>;
301
  fileHistoryWalk(filePath, maxCount): Promise<HistoryEntry[]>;
302
}
303
```
304

305
[Blame Operations](./blame.md) | [Commit History Traversal](./revwalk.md)
306

307
### Configuration and Signatures
308

309
Repository and user configuration management with signature handling for commits and tags.
310

311
```javascript { .api }
312
class Config {
313
  static openDefault(): Promise<Config>;
314
  static openOndisk(path): Promise<Config>;
315
  
316
  getString(name): Promise<string>;
317
  setBool(name, value): Promise<void>;
318
  setString(name, value): Promise<void>;
319
}
320

321
class Signature {
322
  static now(name, email): Signature;
323
  static create(name, email, time, offset): Signature;
324
  static default(repo): Promise<Signature>;
325
  
326
  name(): string;
327
  email(): string;
328
  when(): Time;
329
  toString(withTime): string;
330
}
331
```
332

333
[Configuration Management](./config.md) | [Signature Handling](./signatures.md)
334

335
### Checkout Operations
336

337
Working directory checkout operations for updating files to match specific commits or branches.
338

339
```javascript { .api }
340
class Checkout {
341
  static head(repo, options): Promise<void>;
342
  static index(repo, index, options): Promise<void>;
343
  static tree(repo, treeish, options): Promise<void>;
344
}
345
```
346

347
[Checkout Operations](./checkout.md)
348

349
## Types
350

351
```javascript { .api }
352
interface Signature {
353
  name(): string;
354
  email(): string;
355
  when(): Time;
356
}
357

358
interface Oid {
359
  tostrS(): string;
360
  fmt(): string;
361
  equal(b: Oid): boolean;
362
}
363

364
interface Time {
365
  time: number;
366
  offset: number;
367
}
368

369
interface StatusFile {
370
  path(): string;
371
  statusFlags(): number;
372
}
373

374
interface TreeEntry {
375
  name(): string;
376
  oid(): Oid;
377
  filemode(): number;
378
  type(): number;
379
}
380

381
interface IndexEntry {
382
  path: string;
383
  oid: Oid;
384
  flags: number;
385
  mode: number;
386
}
387

388
interface BlameHunk {
389
  linesInHunk(): number;
390
  finalCommitId(): Oid;
391
  finalStartLineNumber(): number;
392
  finalSignature(): Signature;
393
  origCommitId(): Oid;
394
  origStartLineNumber(): number;
395
  origSignature(): Signature;
396
  origPath(): string;
397
  boundary(): boolean;
398
}
399

400
interface HistoryEntry {
401
  commit: Commit;
402
  status: number;
403
  newName?: string;
404
  oldName?: string;
405
}
406

407
interface CheckoutOptions {
408
  checkoutStrategy?: number;
409
  disableFilters?: boolean;
410
  dirMode?: number;
411
  fileMode?: number;
412
  fileOpenFlags?: number;
413
  notifyCallback?: Function;
414
  notifyFlags?: number;
415
  progressCallback?: Function;
416
  paths?: string[];
417
  baseline?: Tree;
418
  targetDirectory?: string;
419
  ancestorLabel?: string;
420
  ourLabel?: string;
421
  theirLabel?: string;
422
}
423
```