0
# Repository Management
1

2
Core repository operations including initialization, opening, cloning, and configuration. The Repository class serves as the central hub for all Git operations and provides the context for most other operations in NodeGit.
3

4
## Capabilities
5

6
### Repository Discovery and Opening
7

8
Locate and open existing Git repositories.
9

10
```javascript { .api }
11
/**
12
 * Discover the path to a Git repository starting from a given path
13
 * @param {string} path - Starting path for discovery
14
 * @param {boolean} acrossFs - Whether to search across filesystem boundaries
15
 * @param {string} ceilingDirs - Directories to stop searching at
16
 * @returns {Promise<string>} Path to the Git repository
17
 */
18
Repository.discover(path, acrossFs, ceilingDirs): Promise<string>;
19

20
/**
21
 * Open an existing Git repository
22
 * @param {string} path - Path to repository
23
 * @returns {Promise<Repository>} Repository instance
24
 */
25
Repository.open(path): Promise<Repository>;
26

27
/**
28
 * Open a bare Git repository
29
 * @param {string} path - Path to bare repository
30
 * @returns {Promise<Repository>} Repository instance
31
 */
32
Repository.openBare(path): Promise<Repository>;
33

34
/**
35
 * Open repository with extended options
36
 * @param {string} path - Path to repository
37
 * @param {number} flags - Open flags
38
 * @param {string} ceilingDirs - Ceiling directories
39
 * @returns {Promise<Repository>} Repository instance
40
 */
41
Repository.openExt(path, flags, ceilingDirs): Promise<Repository>;
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
const NodeGit = require('nodegit');
48

49
// Discover repository from subdirectory
50
NodeGit.Repository.discover('./src/components', false, '')
51
  .then(function(repoPath) {
52
    console.log('Found repository at:', repoPath);
53
    return NodeGit.Repository.open(repoPath);
54
  })
55
  .then(function(repo) {
56
    // Work with repository
57
  });
58

59
// Open repository directly
60
NodeGit.Repository.open('./my-project')
61
  .then(function(repo) {
62
    console.log('Repository workdir:', repo.workdir());
63
    console.log('Repository path:', repo.path());
64
  });
65
```
66

67
### Repository Initialization
68

69
Create new Git repositories.
70

71
```javascript { .api }
72
/**
73
 * Initialize a new Git repository
74
 * @param {string} path - Path where repository should be created
75
 * @param {number} opts - Initialization options
76
 * @returns {Promise<Repository>} Newly created repository
77
 */
78
Repository.init(path, opts): Promise<Repository>;
79

80
/**
81
 * Initialize repository with extended options
82
 * @param {string} path - Path where repository should be created
83
 * @param {InitOptions} opts - Extended initialization options
84
 * @returns {Promise<Repository>} Newly created repository
85
 */
86
Repository.initExt(path, opts): Promise<Repository>;
87

88
interface InitOptions {
89
  flags: number;
90
  mode: number;
91
  workdirPath: string;
92
  description: string;
93
  templatePath: string;
94
  initialHead: string;
95
  originUrl: string;
96
}
97
```
98

99
**Usage Examples:**
100

101
```javascript
102
// Initialize new repository
103
NodeGit.Repository.init('./new-repo', 0)
104
  .then(function(repo) {
105
    console.log('Created repository at:', repo.workdir());
106
  });
107

108
// Initialize bare repository
109
NodeGit.Repository.init('./bare-repo.git', 1)
110
  .then(function(repo) {
111
    console.log('Created bare repository');
112
  });
113
```
114

115
### Repository Cloning
116

117
Clone remote repositories.
118

119
```javascript { .api }
120
/**
121
 * Clone a remote repository
122
 * @param {string} url - URL of remote repository
123
 * @param {string} localPath - Local path to clone to
124
 * @param {CloneOptions} options - Clone options
125
 * @returns {Promise<Repository>} Cloned repository
126
 */
127
Repository.clone(url, localPath, options): Promise<Repository>;
128

129
interface CloneOptions {
130
  checkoutBranch: string;
131
  fetchOpts: FetchOptions;
132
  bare: boolean;
133
  localPath: string;
134
  repositoryCallback: Function;
135
  remoteCallback: Function;
136
}
137

138
interface FetchOptions {
139
  callbacks: RemoteCallbacks;
140
  proxyOpts: ProxyOptions;
141
  downloadTags: number;
142
}
143

144
interface RemoteCallbacks {
145
  credentials: Function;
146
  certificateCheck: Function;
147
  transferProgress: Function;
148
  updateTips: Function;
149
  packProgress: Function;
150
  pushTransferProgress: Function;
151
  pushUpdateReference: Function;
152
}
153
```
154

155
**Usage Examples:**
156

157
```javascript
158
// Basic clone
159
NodeGit.Clone('https://github.com/user/repo.git', './local-repo')
160
  .then(function(repo) {
161
    console.log('Cloned to:', repo.workdir());
162
  });
163

164
// Clone with options
165
const cloneOptions = {
166
  fetchOpts: {
167
    callbacks: {
168
      certificateCheck: function() {
169
        return 0; // Accept all certificates
170
      },
171
      credentials: function(url, userName) {
172
        return NodeGit.Cred.sshKeyFromAgent(userName);
173
      }
174
    }
175
  }
176
};
177

178
NodeGit.Clone('git@github.com:user/repo.git', './local-repo', cloneOptions)
179
  .then(function(repo) {
180
    console.log('Cloned with SSH:', repo.workdir());
181
  });
182
```
183

184
### Repository Properties and State
185

186
Access repository information and state.
187

188
```javascript { .api }
189
/**
190
 * Check if repository is bare (no working directory)
191
 * @returns {boolean} True if bare repository
192
 */
193
repository.bare(): boolean;
194

195
/**
196
 * Check if repository is empty (no commits)
197
 * @returns {Promise<boolean>} True if empty
198
 */
199
repository.isEmpty(): Promise<boolean>;
200

201
/**
202
 * Check if repository is shallow
203
 * @returns {boolean} True if shallow
204
 */
205
repository.isShallow(): boolean;
206

207
/**
208
 * Get repository working directory path
209
 * @returns {string} Working directory path
210
 */
211
repository.workdir(): string;
212

213
/**
214
 * Get repository .git directory path
215
 * @returns {string} Git directory path
216
 */
217
repository.path(): string;
218

219
/**
220
 * Get common directory path
221
 * @returns {string} Common directory path
222
 */
223
repository.commondir(): string;
224

225
/**
226
 * Set working directory
227
 * @param {string} path - New working directory path
228
 * @param {boolean} updateGitlink - Whether to update gitlink
229
 * @returns {Promise<void>}
230
 */
231
repository.setWorkdir(path, updateGitlink): Promise<void>;
232
```
233

234
### Repository Configuration
235

236
Access and modify repository configuration.
237

238
```javascript { .api }
239
/**
240
 * Get repository configuration
241
 * @returns {Promise<Config>} Configuration object
242
 */
243
repository.config(): Promise<Config>;
244

245
/**
246
 * Get configuration snapshot
247
 * @returns {Promise<Config>} Configuration snapshot
248
 */
249
repository.configSnapshot(): Promise<Config>;
250
```
251

252
### Repository Head and References
253

254
Access HEAD and reference information.
255

256
```javascript { .api }
257
/**
258
 * Get HEAD reference
259
 * @returns {Promise<Reference>} HEAD reference
260
 */
261
repository.head(): Promise<Reference>;
262

263
/**
264
 * Check if HEAD is detached
265
 * @returns {Promise<boolean>} True if HEAD is detached
266
 */
267
repository.headDetached(): Promise<boolean>;
268

269
/**
270
 * Check if HEAD is unborn (no commits yet)
271
 * @returns {Promise<boolean>} True if HEAD is unborn
272
 */
273
repository.headUnborn(): Promise<boolean>;
274

275
/**
276
 * Get current branch
277
 * @returns {Promise<Reference>} Current branch reference
278
 */
279
repository.getCurrentBranch(): Promise<Reference>;
280

281
/**
282
 * Get HEAD commit
283
 * @returns {Promise<Commit>} HEAD commit
284
 */
285
repository.getHeadCommit(): Promise<Commit>;
286
```
287

288
**Usage Examples:**
289

290
```javascript
291
const repo = await NodeGit.Repository.open('./my-repo');
292

293
// Check repository state
294
if (repo.bare()) {
295
  console.log('This is a bare repository');
296
}
297

298
if (await repo.isEmpty()) {
299
  console.log('Repository has no commits');
300
}
301

302
// Get current branch and commit
303
const currentBranch = await repo.getCurrentBranch();
304
console.log('Current branch:', currentBranch.shorthand());
305

306
const headCommit = await repo.getHeadCommit();
307
console.log('Latest commit:', headCommit.sha());
308
console.log('Commit message:', headCommit.message());
309
```
310

311
### Repository Index and Database
312

313
Access repository index and object database.
314

315
```javascript { .api }
316
/**
317
 * Get repository index
318
 * @returns {Promise<Index>} Repository index
319
 */
320
repository.index(): Promise<Index>;
321

322
/**
323
 * Get object database
324
 * @returns {Promise<Odb>} Object database
325
 */
326
repository.odb(): Promise<Odb>;
327
```
328

329
### Repository Status
330

331
Get repository status and working directory state.
332

333
```javascript { .api }
334
/**
335
 * Get repository status
336
 * @returns {Promise<StatusFile[]>} Array of status files
337
 */
338
repository.getStatus(): Promise<StatusFile[]>;
339

340
/**
341
 * Get status with options
342
 * @param {StatusOptions} opts - Status options
343
 * @returns {Promise<StatusFile[]>} Array of status files
344
 */
345
repository.getStatusExt(opts): Promise<StatusFile[]>;
346

347
/**
348
 * Check if path is ignored
349
 * @param {string} path - Path to check
350
 * @returns {Promise<boolean>} True if ignored
351
 */
352
repository.isIgnored(path): Promise<boolean>;
353

354
interface StatusOptions {
355
  flags: number;
356
  pathspec: string[];
357
  baseline: Tree;
358
}
359
```
360

361
**Usage Examples:**
362

363
```javascript
364
// Get repository status
365
const statusFiles = await repo.getStatus();
366
statusFiles.forEach(function(file) {
367
  console.log('File:', file.path());
368
  console.log('Status:', file.statusFlags());
369
});
370

371
// Check if file is ignored
372
const isIgnored = await repo.isIgnored('temp.log');
373
if (isIgnored) {
374
  console.log('File is ignored by .gitignore');
375
}
376
```
377

378
### Convenience Methods
379

380
High-level convenience methods for common operations.
381

382
```javascript { .api }
383
/**
384
 * Create commit on HEAD with convenience
385
 * @param {string[]} filesToAdd - Files to add to commit
386
 * @param {Signature} author - Author signature
387
 * @param {Signature} committer - Committer signature  
388
 * @param {string} message - Commit message
389
 * @returns {Promise<Oid>} New commit OID
390
 */
391
repository.createCommitOnHead(filesToAdd, author, committer, message): Promise<Oid>;
392

393
/**
394
 * Checkout HEAD
395
 * @param {CheckoutOptions} opts - Checkout options
396
 * @returns {Promise<void>}
397
 */
398
repository.checkoutHead(opts): Promise<void>;
399
```
400

401
**Usage Examples:**
402

403
```javascript
404
const signature = NodeGit.Signature.now('John Doe', 'john@example.com');
405

406
// Create commit with convenience method
407
await repo.createCommitOnHead(
408
  ['file1.txt', 'file2.txt'],
409
  signature,
410
  signature,
411
  'Add new features'
412
);
413

414
// Checkout HEAD (discard working directory changes)
415
await repo.checkoutHead({
416
  strategy: NodeGit.Checkout.STRATEGY.FORCE
417
});
418
```