0
# Working Directory Operations
1

2
Functions for staging files, checking status, and managing the working directory.
3

4
## Capabilities
5

6
### Add Files to Staging
7

8
Stages files for commit by adding them to the Git index.
9

10
```javascript { .api }
11
/**
12
 * Stage a file for commit
13
 * @param args.fs - File system client
14
 * @param args.dir - Working tree directory path
15
 * @param args.gitdir - Git directory path
16
 * @param args.filepath - Path to file to stage (can be string or string[])
17
 * @param args.cache - Cache object
18
 * @param args.force - Add to index even if matches gitignore
19
 * @param args.parallel - Process each input file in parallel
20
 * @returns Promise resolving when file is staged
21
 */
22
function add(args: {
23
  fs: FsClient;
24
  dir?: string;
25
  gitdir?: string;
26
  filepath: string | string[];
27
  cache?: object;
28
  force?: boolean;
29
  parallel?: boolean;
30
}): Promise<void>;
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
import git from "isomorphic-git";
37
import fs from "fs";
38

39
// Stage a single file
40
await git.add({
41
  fs,
42
  dir: "/path/to/repo",
43
  filepath: "src/index.js"
44
});
45

46
// Stage multiple files
47
const files = ["src/index.js", "README.md", "package.json"];
48
for (const filepath of files) {
49
  await git.add({ fs, dir: "/path/to/repo", filepath });
50
}
51
```
52

53
### Remove Files
54

55
Removes files from the index and optionally from the working directory.
56

57
```javascript { .api }
58
/**
59
 * Remove a file from the index and working directory
60
 * @param args.fs - File system client
61
 * @param args.dir - Working tree directory path
62
 * @param args.gitdir - Git directory path
63
 * @param args.filepath - Path to file to remove
64
 * @param args.cache - Cache object
65
 * @returns Promise resolving when file is removed
66
 */
67
function remove(args: {
68
  fs: FsClient;
69
  dir?: string;
70
  gitdir?: string;
71
  filepath: string;
72
  cache?: object;
73
}): Promise<void>;
74
```
75

76
**Usage Example:**
77

78
```javascript
79
import git from "isomorphic-git";
80
import fs from "fs";
81

82
// Remove a file
83
await git.remove({
84
  fs,
85
  dir: "/path/to/repo",
86
  filepath: "old-file.js"
87
});
88
```
89

90
### Check File Status
91

92
Returns the status of a single file in the working directory.
93

94
```javascript { .api }
95
/**
96
 * Get the status of a file
97
 * @param args.fs - File system client
98
 * @param args.dir - Working tree directory path
99
 * @param args.gitdir - Git directory path
100
 * @param args.filepath - Path to file to check
101
 * @param args.cache - Cache object
102
 * @returns Promise resolving to status string
103
 */
104
function status(args: {
105
  fs: FsClient;
106
  dir?: string;
107
  gitdir?: string;
108
  filepath: string;
109
  cache?: object;
110
}): Promise<string>;
111
```
112

113
**Status Values:**
114
- `"ignored"` - File is ignored by .gitignore
115
- `"unmodified"` - File is unchanged from HEAD commit
116
- `"*modified"` - File is modified in working directory but not staged
117
- `"*deleted"` - File is deleted in working directory but not staged
118
- `"*added"` - File is new in working directory but not staged
119
- `"absent"` - File not present in HEAD commit, staging area, or working dir
120
- `"modified"` - File is staged for commit
121
- `"deleted"` - File is staged for deletion
122
- `"added"` - File is staged as new
123
- `"*unmodified"` - Working dir and HEAD commit match, but index differs
124
- `"*absent"` - File not present in working dir or HEAD commit, but present in the index
125
- `"*undeleted"` - File was deleted from the index, but is still in the working dir
126
- `"*undeletemodified"` - File was deleted from the index, but is present with modifications in the working dir
127

128
**Usage Example:**
129

130
```javascript
131
import git from "isomorphic-git";
132
import fs from "fs";
133

134
const fileStatus = await git.status({
135
  fs,
136
  dir: "/path/to/repo",
137
  filepath: "src/index.js"
138
});
139
console.log(fileStatus); // "*modified"
140
```
141

142
### Status Matrix
143

144
Returns detailed status information for multiple files as a matrix.
145

146
```javascript { .api }
147
/**
148
 * Get detailed status matrix for repository files
149
 * @param args.fs - File system client
150
 * @param args.dir - Working tree directory path
151
 * @param args.gitdir - Git directory path
152
 * @param args.ref - Git reference to compare against (defaults to HEAD)
153
 * @param args.filepaths - Specific files to check (defaults to all files)
154
 * @param args.filter - Filter function for files
155
 * @param args.cache - Cache object
156
 * @param args.ignored - Whether to include ignored files
157
 * @returns Promise resolving to array of [filepath, HEAD, WORKDIR, STAGE] tuples
158
 */
159
function statusMatrix(args: {
160
  fs: FsClient;
161
  dir?: string;
162
  gitdir?: string;
163
  ref?: string;
164
  filepaths?: string[];
165
  filter?: (filepath: string) => boolean;
166
  cache?: object;
167
  ignored?: boolean;
168
}): Promise<Array<[string, number, number, number]>>;
169
```
170

171
**Matrix Values:**
172
- `0` = File is absent
173
- `1` = File is present  
174
- `2` = File is present but differs from comparison
175

176
**Usage Examples:**
177

178
```javascript
179
import git from "isomorphic-git";
180
import fs from "fs";
181

182
// Get status for all files
183
const matrix = await git.statusMatrix({
184
  fs,
185
  dir: "/path/to/repo"
186
});
187

188
// Process the status matrix
189
for (const [filepath, HEAD, WORKDIR, STAGE] of matrix) {
190
  if (HEAD === 1 && WORKDIR === 2 && STAGE === 1) {
191
    console.log(`${filepath} is modified in working directory`);
192
  } else if (HEAD === 0 && WORKDIR === 1 && STAGE === 0) {
193
    console.log(`${filepath} is untracked`);
194
  } else if (HEAD === 1 && WORKDIR === 1 && STAGE === 2) {
195
    console.log(`${filepath} is staged for commit`);
196
  }
197
}
198

199
// Get status for specific files only
200
const specificMatrix = await git.statusMatrix({
201
  fs,
202
  dir: "/path/to/repo",
203
  filepaths: ["src/index.js", "README.md"]
204
});
205
```
206

207
### List Files
208

209
Lists all files tracked by Git in the repository.
210

211
```javascript { .api }
212
/**
213
 * List all files in the repository
214
 * @param args.fs - File system client
215
 * @param args.dir - Working tree directory path
216
 * @param args.gitdir - Git directory path
217
 * @param args.ref - Git reference to list files from
218
 * @param args.cache - Cache object
219
 * @returns Promise resolving to array of file paths
220
 */
221
function listFiles(args: {
222
  fs: FsClient;
223
  dir?: string;
224
  gitdir?: string;
225
  ref?: string;
226
  cache?: object;
227
}): Promise<string[]>;
228
```
229

230
**Usage Examples:**
231

232
```javascript
233
import git from "isomorphic-git";
234
import fs from "fs";
235

236
// List all files in current HEAD
237
const files = await git.listFiles({
238
  fs,
239
  dir: "/path/to/repo"
240
});
241
console.log(files); // ["src/index.js", "README.md", "package.json", ...]
242

243
// List files from specific commit
244
const filesAtCommit = await git.listFiles({
245
  fs,
246
  dir: "/path/to/repo",
247
  ref: "abc123"
248
});
249
```
250

251
### Check if File is Ignored
252

253
Checks whether a file is ignored by .gitignore rules.
254

255
```javascript { .api }
256
/**
257
 * Check if a file is ignored by .gitignore
258
 * @param args.fs - File system client
259
 * @param args.dir - Working tree directory path
260
 * @param args.gitdir - Git directory path
261
 * @param args.filepath - Path to file to check
262
 * @returns Promise resolving to true if ignored, false otherwise
263
 */
264
function isIgnored(args: {
265
  fs: FsClient;
266
  dir?: string;
267
  gitdir?: string;
268
  filepath: string;
269
}): Promise<boolean>;
270
```
271

272
**Usage Example:**
273

274
```javascript
275
import git from "isomorphic-git";
276
import fs from "fs";
277

278
const ignored = await git.isIgnored({
279
  fs,
280
  dir: "/path/to/repo",
281
  filepath: "node_modules/some-package/index.js"
282
});
283
console.log(ignored ? "File is ignored" : "File is not ignored");
284
```
285

286
### Reset Index
287

288
Resets the index to match a specific tree or commit.
289

290
```javascript { .api }
291
/**
292
 * Reset the index to match a specific tree
293
 * @param args.fs - File system client
294
 * @param args.dir - Working tree directory path
295
 * @param args.gitdir - Git directory path
296
 * @param args.ref - Reference to reset to
297
 * @param args.filepaths - Specific files to reset
298
 * @param args.cache - Cache object
299
 * @returns Promise resolving when reset is complete
300
 */
301
function resetIndex(args: {
302
  fs: FsClient;
303
  dir?: string;
304
  gitdir?: string;
305
  ref?: string;
306
  filepaths?: string[];
307
  cache?: object;
308
}): Promise<void>;
309
```
310

311
**Usage Examples:**
312

313
```javascript
314
import git from "isomorphic-git";
315
import fs from "fs";
316

317
// Reset entire index to HEAD
318
await git.resetIndex({
319
  fs,
320
  dir: "/path/to/repo",
321
  ref: "HEAD"
322
});
323

324
// Reset specific files
325
await git.resetIndex({
326
  fs,
327
  dir: "/path/to/repo",
328
  ref: "HEAD",
329
  filepaths: ["src/index.js", "README.md"]
330
});
331
```
332

333
### Update Index
334

335
Updates the index with specific file changes.
336

337
```javascript { .api }
338
/**
339
 * Update the index with file changes
340
 * @param args.fs - File system client
341
 * @param args.dir - Working tree directory path
342
 * @param args.gitdir - Git directory path
343
 * @param args.filepath - Path to file to update
344
 * @param args.oid - Object ID to use
345
 * @param args.mode - File mode
346
 * @param args.add - Add file to index
347
 * @param args.remove - Remove file from index
348
 * @param args.force - Force update
349
 * @param args.cache - Cache object
350
 * @returns Promise resolving when update is complete
351
 */
352
function updateIndex(args: {
353
  fs: FsClient;
354
  dir?: string;
355
  gitdir?: string;
356
  filepath: string;
357
  oid?: string;
358
  mode?: number;
359
  add?: boolean;
360
  remove?: boolean;
361
  force?: boolean;
362
  cache?: object;
363
}): Promise<void>;
364
```
365

366
**Usage Example:**
367

368
```javascript
369
import git from "isomorphic-git";
370
import fs from "fs";
371

372
// Update index entry for a file
373
await git.updateIndex({
374
  fs,
375
  dir: "/path/to/repo",
376
  filepath: "src/index.js",
377
  add: true
378
});
379
```