0
# Configuration Management
1

2
Reading and writing Git configuration values.
3

4
## Capabilities
5

6
### Get Configuration Value
7

8
Retrieves a configuration value from Git config.
9

10
```javascript { .api }
11
/**
12
 * Get a configuration value
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.path - Configuration key path (e.g., 'user.name')
17
 * @returns Promise resolving to configuration value
18
 */
19
function getConfig(args: {
20
  fs: FsClient;
21
  dir?: string;
22
  gitdir?: string;
23
  path: string;
24
}): Promise<any>;
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
import git from "isomorphic-git";
31
import fs from "fs";
32

33
// Get user name
34
const userName = await git.getConfig({
35
  fs,
36
  dir: "/path/to/repo",
37
  path: "user.name"
38
});
39
console.log("User name:", userName);
40

41
// Get user email
42
const userEmail = await git.getConfig({
43
  fs,
44
  dir: "/path/to/repo", 
45
  path: "user.email"
46
});
47
console.log("User email:", userEmail);
48

49
// Get remote URL
50
const remoteUrl = await git.getConfig({
51
  fs,
52
  dir: "/path/to/repo",
53
  path: "remote.origin.url"
54
});
55
console.log("Origin URL:", remoteUrl);
56

57
// Get core configuration
58
const autocrlf = await git.getConfig({
59
  fs,
60
  dir: "/path/to/repo",
61
  path: "core.autocrlf"
62
});
63
console.log("Auto CRLF:", autocrlf);
64
```
65

66
### Get All Configuration Values
67

68
Retrieves all values for a configuration key that can have multiple values.
69

70
```javascript { .api }
71
/**
72
 * Get all values for a configuration key
73
 * @param args.fs - File system client
74
 * @param args.dir - Working tree directory path
75
 * @param args.gitdir - Git directory path
76
 * @param args.path - Configuration key path
77
 * @returns Promise resolving to array of all values
78
 */
79
function getConfigAll(args: {
80
  fs: FsClient;
81
  dir?: string;
82
  gitdir?: string;
83
  path: string;
84
}): Promise<any[]>;
85
```
86

87
**Usage Example:**
88

89
```javascript
90
import git from "isomorphic-git";
91
import fs from "fs";
92

93
// Get all remote URLs (useful for multi-URL remotes)
94
const allUrls = await git.getConfigAll({
95
  fs,
96
  dir: "/path/to/repo",
97
  path: "remote.origin.url"
98
});
99
console.log("All origin URLs:", allUrls);
100

101
// Get all submodule paths
102
const submodules = await git.getConfigAll({
103
  fs,
104
  dir: "/path/to/repo",
105
  path: "submodule.*.path"
106
});
107
console.log("Submodule paths:", submodules);
108
```
109

110
### Set Configuration Value
111

112
Sets a configuration value in Git config.
113

114
```javascript { .api }
115
/**
116
 * Set a configuration value
117
 * @param args.fs - File system client
118
 * @param args.dir - Working tree directory path
119
 * @param args.gitdir - Git directory path
120
 * @param args.path - Configuration key path
121
 * @param args.value - Value to set
122
 * @param args.append - Append to existing values instead of replacing
123
 * @returns Promise resolving when configuration is set
124
 */
125
function setConfig(args: {
126
  fs: FsClient;
127
  dir?: string;
128
  gitdir?: string;
129
  path: string;
130
  value: any;
131
  append?: boolean;
132
}): Promise<void>;
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
import git from "isomorphic-git";
139
import fs from "fs";
140

141
// Set user name and email
142
await git.setConfig({
143
  fs,
144
  dir: "/path/to/repo",
145
  path: "user.name",
146
  value: "John Doe"
147
});
148

149
await git.setConfig({
150
  fs,
151
  dir: "/path/to/repo",
152
  path: "user.email", 
153
  value: "john@example.com"
154
});
155

156
// Set core configuration
157
await git.setConfig({
158
  fs,
159
  dir: "/path/to/repo",
160
  path: "core.autocrlf",
161
  value: "input"
162
});
163

164
// Set boolean value
165
await git.setConfig({
166
  fs,
167
  dir: "/path/to/repo",
168
  path: "core.bare",
169
  value: false
170
});
171

172
// Set numeric value
173
await git.setConfig({
174
  fs,
175
  dir: "/path/to/repo",
176
  path: "http.postBuffer",
177
  value: 524288000
178
});
179

180
// Append to multi-value configuration
181
await git.setConfig({
182
  fs,
183
  dir: "/path/to/repo",
184
  path: "remote.origin.url",
185
  value: "https://backup.example.com/repo.git",
186
  append: true
187
});
188
```
189

190
## Common Configuration Patterns
191

192
### User Configuration
193

194
Set up user identity for commits:
195

196
```javascript
197
import git from "isomorphic-git";
198
import fs from "fs";
199

200
// Configure user identity
201
await git.setConfig({
202
  fs,
203
  dir: "/path/to/repo",
204
  path: "user.name",
205
  value: "Your Name"
206
});
207

208
await git.setConfig({
209
  fs,
210
  dir: "/path/to/repo", 
211
  path: "user.email",
212
  value: "your.email@example.com"
213
});
214

215
// Verify configuration
216
const name = await git.getConfig({
217
  fs,
218
  dir: "/path/to/repo",
219
  path: "user.name"
220
});
221
const email = await git.getConfig({
222
  fs,
223
  dir: "/path/to/repo",
224
  path: "user.email"
225
});
226
console.log(`Configured as: ${name} <${email}>`);
227
```
228

229
### Remote Configuration
230

231
Configure remote repositories:
232

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

237
// Set remote URL
238
await git.setConfig({
239
  fs,
240
  dir: "/path/to/repo",
241
  path: "remote.origin.url",
242
  value: "https://github.com/user/repo.git"
243
});
244

245
// Set fetch refspec
246
await git.setConfig({
247
  fs,
248
  dir: "/path/to/repo",
249
  path: "remote.origin.fetch",
250
  value: "+refs/heads/*:refs/remotes/origin/*"
251
});
252

253
// Get remote configuration
254
const remoteUrl = await git.getConfig({
255
  fs,
256
  dir: "/path/to/repo",
257
  path: "remote.origin.url"
258
});
259
const fetchSpec = await git.getConfig({
260
  fs,
261
  dir: "/path/to/repo",
262
  path: "remote.origin.fetch"
263
});
264
console.log(`Remote: ${remoteUrl}`);
265
console.log(`Fetch: ${fetchSpec}`);
266
```
267

268
### Branch Configuration
269

270
Configure branch tracking:
271

272
```javascript
273
import git from "isomorphic-git";
274
import fs from "fs";
275

276
// Set up branch tracking
277
await git.setConfig({
278
  fs,
279
  dir: "/path/to/repo",
280
  path: "branch.main.remote",
281
  value: "origin"
282
});
283

284
await git.setConfig({
285
  fs,
286
  dir: "/path/to/repo",
287
  path: "branch.main.merge",
288
  value: "refs/heads/main"
289
});
290

291
// Check branch configuration
292
const branchRemote = await git.getConfig({
293
  fs,
294
  dir: "/path/to/repo",
295
  path: "branch.main.remote"
296
});
297
const branchMerge = await git.getConfig({
298
  fs,
299
  dir: "/path/to/repo",
300
  path: "branch.main.merge"
301
});
302
console.log(`Branch tracks: ${branchRemote}/${branchMerge}`);
303
```
304

305
### Core Configuration
306

307
Configure core Git behavior:
308

309
```javascript
310
import git from "isomorphic-git";
311
import fs from "fs";
312

313
// Configure line ending handling
314
await git.setConfig({
315
  fs,
316
  dir: "/path/to/repo",
317
  path: "core.autocrlf",
318
  value: "input" // or "true" on Windows, "false" for no conversion
319
});
320

321
// Configure file mode tracking
322
await git.setConfig({
323
  fs,
324
  dir: "/path/to/repo",
325
  path: "core.filemode",
326
  value: true // Set to false on Windows or filesystems without executable bit
327
});
328

329
// Configure default editor
330
await git.setConfig({
331
  fs,
332
  dir: "/path/to/repo",
333
  path: "core.editor",
334
  value: "code --wait" // VS Code as editor
335
});
336

337
// Configure merge tool
338
await git.setConfig({
339
  fs,
340
  dir: "/path/to/repo",
341
  path: "merge.tool",
342
  value: "vscode"
343
});
344
```
345

346
### HTTP Configuration
347

348
Configure HTTP behavior for Git operations:
349

350
```javascript
351
import git from "isomorphic-git";
352
import fs from "fs";
353

354
// Set HTTP buffer size
355
await git.setConfig({
356
  fs,
357
  dir: "/path/to/repo",
358
  path: "http.postBuffer",
359
  value: 524288000 // 500MB
360
});
361

362
// Configure SSL verification
363
await git.setConfig({
364
  fs,
365
  dir: "/path/to/repo",
366
  path: "http.sslVerify",
367
  value: true
368
});
369

370
// Set HTTP timeout
371
await git.setConfig({
372
  fs,
373
  dir: "/path/to/repo",
374
  path: "http.timeout",
375
  value: 60
376
});
377
```
378

379
## Configuration Locations
380

381
Git configuration can be stored in different locations with different precedence:
382

383
1. **System config** (`/etc/gitconfig`) - Affects all users
384
2. **Global config** (`~/.gitconfig`) - Affects current user
385
3. **Local config** (`.git/config`) - Affects current repository
386

387
isomorphic-git primarily works with local repository configuration. For global configuration, you would need to specify the appropriate file path.
388

389
## Configuration File Format
390

391
Git configuration files use INI format:
392

393
```ini
394
[user]
395
    name = John Doe
396
    email = john@example.com
397

398
[remote "origin"]
399
    url = https://github.com/user/repo.git
400
    fetch = +refs/heads/*:refs/remotes/origin/*
401

402
[branch "main"]
403
    remote = origin
404
    merge = refs/heads/main
405

406
[core]
407
    autocrlf = input
408
    filemode = true
409
```