0
# Index Operations
1

2
Index operations for staging changes, managing the Git index, and preparing commits. The Git index (also known as the staging area) tracks file changes and determines what will be included in the next commit.
3

4
## Capabilities
5

6
### Index Access and Creation
7

8
Access and manipulate the Git index.
9

10
```javascript { .api }
11
/**
12
 * Open index file directly
13
 * @param {string} indexPath - Path to index file
14
 * @returns {Promise<Index>} Index object
15
 */
16
Index.open(indexPath): Promise<Index>;
17
```
18

19
### Adding Files to Index
20

21
Stage files and changes for commit.
22

23
```javascript { .api }
24
/**
25
 * Add single file to index by pathspec
26
 * @param {string} pathspec - File pathspec to add
27
 * @returns {Promise<void>}
28
 */
29
index.add(pathspec): Promise<void>;
30

31
/**
32
 * Add file to index by path
33
 * @param {string} path - File path to add
34
 * @returns {Promise<void>}
35
 */
36
index.addByPath(path): Promise<void>;
37

38
/**
39
 * Add all files matching pathspec
40
 * @param {string|string[]} pathspec - Pathspec or array of pathspecs (defaults to "*")
41
 * @param {number} flags - Add flags
42
 * @param {Function} matchedCallback - Callback for matched files
43
 * @returns {Promise<void>}
44
 */
45
index.addAll(pathspec, flags, matchedCallback): Promise<void>;
46
```
47

48
**Usage Examples:**
49

50
```javascript
51
const NodeGit = require('nodegit');
52

53
const repo = await NodeGit.Repository.open('./my-repo');
54
const index = await repo.index();
55

56
// Add single file
57
await index.addByPath('README.md');
58

59
// Add multiple files with pathspec
60
await index.add('src/*.js');
61

62
// Add all modified files
63
await index.addAll('*', NodeGit.Index.ADD_OPTION.ADD_DEFAULT, function(path, pathspec) {
64
  console.log('Adding:', path);
65
});
66

67
// Write changes to disk
68
await index.write();
69
```
70

71
### Removing Files from Index
72

73
Remove files from the staging area.
74

75
```javascript { .api }
76
/**
77
 * Remove file from index by path
78
 * @param {string} path - File path to remove
79
 * @param {number} stage - Stage number (0 for normal, 1-3 for conflicts)
80
 * @returns {Promise<void>}
81
 */
82
index.remove(path, stage): Promise<void>;
83

84
/**
85
 * Remove file from index by path
86
 * @param {string} path - File path to remove
87
 * @returns {Promise<void>}
88
 */
89
index.removeByPath(path): Promise<void>;
90

91
/**
92
 * Remove all files matching pathspec
93
 * @param {string|string[]} pathspec - Pathspec or array of pathspecs (defaults to "*")
94
 * @param {Function} matchedCallback - Callback for matched files
95
 * @returns {Promise<void>}
96
 */
97
index.removeAll(pathspec, matchedCallback): Promise<void>;
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
// Remove single file
104
await index.removeByPath('temp.txt');
105

106
// Remove all files matching pattern
107
await index.removeAll('*.tmp', function(path, pathspec) {
108
  console.log('Removing:', path);
109
});
110

111
await index.write();
112
```
113

114
### Updating Index
115

116
Update existing files in the index.
117

118
```javascript { .api }
119
/**
120
 * Update all files matching pathspec
121
 * @param {string|string[]} pathspec - Pathspec or array of pathspecs (defaults to "*")
122
 * @param {Function} matchedCallback - Callback for matched files
123
 * @returns {Promise<void>}
124
 */
125
index.updateAll(pathspec, matchedCallback): Promise<void>;
126
```
127

128
### Index Information and State
129

130
Access index information and entries.
131

132
```javascript { .api }
133
/**
134
 * Get number of entries in index
135
 * @returns {number} Entry count
136
 */
137
index.entryCount(): number;
138

139
/**
140
 * Get all index entries
141
 * @returns {IndexEntry[]} Array of index entries
142
 */
143
index.entries(): IndexEntry[];
144

145
/**
146
 * Get index entry by position
147
 * @param {number} pos - Entry position
148
 * @returns {IndexEntry} Index entry
149
 */
150
index.getByIndex(pos): IndexEntry;
151

152
/**
153
 * Get index entry by path
154
 * @param {string} path - File path
155
 * @param {number} stage - Stage number (0 for normal, 1-3 for conflicts)
156
 * @returns {IndexEntry} Index entry
157
 */
158
index.getByPath(path, stage): IndexEntry;
159

160
/**
161
 * Check if index has conflicts
162
 * @returns {boolean} True if conflicts exist
163
 */
164
index.hasConflicts(): boolean;
165
```
166

167
**Usage Examples:**
168

169
```javascript
170
const index = await repo.index();
171

172
console.log('Index entries:', index.entryCount());
173

174
// List all staged files
175
const entries = index.entries();
176
entries.forEach(function(entry) {
177
  console.log('File:', entry.path);
178
  console.log('Stage:', entry.stage);
179
  console.log('Mode:', entry.mode.toString(8));
180
});
181

182
// Check specific file
183
const entry = index.getByPath('src/main.js', 0);
184
if (entry) {
185
  console.log('File is staged:', entry.path);
186
}
187

188
// Check for conflicts
189
if (index.hasConflicts()) {
190
  console.log('Index has merge conflicts');
191
}
192
```
193

194
### Index I/O Operations
195

196
Read from and write to index.
197

198
```javascript { .api }
199
/**
200
 * Read index from disk
201
 * @param {boolean} force - Force read even if not changed
202
 * @returns {Promise<void>}
203
 */
204
index.read(force): Promise<void>;
205

206
/**
207
 * Write index to disk
208
 * @returns {Promise<void>}
209
 */
210
index.write(): Promise<void>;
211

212
/**
213
 * Write index as tree object
214
 * @returns {Promise<Oid>} Tree OID
215
 */
216
index.writeTree(): Promise<Oid>;
217

218
/**
219
 * Write index as tree to repository
220
 * @param {Repository} repo - Target repository
221
 * @returns {Promise<Oid>} Tree OID
222
 */
223
index.writeTreeTo(repo): Promise<Oid>;
224
```
225

226
**Usage Examples:**
227

228
```javascript
229
// Refresh index from disk
230
await index.read(true);
231

232
// Write changes and create tree
233
await index.write();
234
const treeOid = await index.writeTree();
235

236
// Use tree for commit
237
const tree = await NodeGit.Tree.lookup(repo, treeOid);
238
const signature = NodeGit.Signature.now('John Doe', 'john@example.com');
239

240
const commitOid = await NodeGit.Commit.create(
241
  repo,
242
  'HEAD',
243
  signature,
244
  signature,
245
  null,
246
  'Commit message',
247
  tree,
248
  1,
249
  [await repo.getHeadCommit()]
250
);
251
```
252

253
### Tree Operations
254

255
Read trees into index.
256

257
```javascript { .api }
258
/**
259
 * Read tree into index
260
 * @param {Tree} tree - Tree to read
261
 * @returns {Promise<void>}
262
 */
263
index.readTree(tree): Promise<void>;
264
```
265

266
**Usage Examples:**
267

268
```javascript
269
// Read commit tree into index
270
const commit = await repo.getHeadCommit();
271
const tree = await commit.getTree();
272

273
await index.readTree(tree);
274
await index.write();
275
```
276

277
### Index Maintenance
278

279
Clear and clean up index.
280

281
```javascript { .api }
282
/**
283
 * Clear all entries from index
284
 * @returns {Promise<void>}
285
 */
286
index.clear(): Promise<void>;
287

288
/**
289
 * Clean up conflict state
290
 * @returns {Promise<void>}
291
 */
292
index.conflictCleanup(): Promise<void>;
293
```
294

295
**Usage Examples:**
296

297
```javascript
298
// Clear entire index
299
await index.clear();
300
await index.write();
301

302
// Clean up after resolving conflicts
303
await index.conflictCleanup();
304
await index.write();
305
```
306

307
## Types
308

309
```javascript { .api }
310
interface IndexEntry {
311
  path: string;
312
  oid: Oid;
313
  dev: number;
314
  ino: number;
315
  mode: number;
316
  uid: number;
317
  gid: number;
318
  fileSize: number;
319
  flags: number;
320
  flagsExtended: number;
321
  stage: number;
322
}
323

324
// Index add flags
325
Index.ADD_OPTION = {
326
  ADD_DEFAULT: 0,
327
  ADD_FORCE: 1,
328
  ADD_DISABLE_PATHSPEC_MATCH: 2,
329
  ADD_CHECK_PATHSPEC: 4
330
};
331

332
// Index capabilities
333
Index.CAPABILITY = {
334
  IGNORE_CASE: 1,
335
  NO_FILEMODE: 2, 
336
  NO_SYMLINKS: 4,
337
  FROM_OWNER: -1
338
};
339

340
// Index entry flags
341
Index.ENTRY_FLAG = {
342
  ENTRY_EXTENDED: 0x4000,
343
  ENTRY_VALID: 0x8000
344
};
345

346
// Index entry extended flags
347
Index.ENTRY_EXTENDED_FLAG = {
348
  ENTRY_INTENT_TO_ADD: 1 << 13,
349
  ENTRY_SKIP_WORKTREE: 1 << 14,
350
  S: 1 << 15,
351
  ENTRY_UPTODATE: 1 << 2
352
};
353
```