0
# Commit Operations
1

2
Creating commits, reading commit history, and commit-related operations.
3

4
## Capabilities
5

6
### Create Commit
7

8
Creates a new commit with the staged changes.
9

10
```javascript { .api }
11
/**
12
 * Create a new 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.message - Commit message (required unless amending)
17
 * @param args.author - Author information
18
 * @param args.committer - Committer information (defaults to author)
19
 * @param args.signingKey - PGP signing key
20
 * @param args.onSign - Signing callback
21
 * @param args.amend - Replace the last commit
22
 * @param args.dryRun - Simulate commit without creating it
23
 * @param args.noUpdateBranch - Don't update branch pointer
24
 * @param args.ref - Branch reference to commit to
25
 * @param args.parent - Parent commit SHA(s)
26
 * @param args.tree - Tree SHA to use
27
 * @param args.cache - Cache object
28
 * @returns Promise resolving to new commit SHA
29
 */
30
function commit(args: {
31
  fs: FsClient;
32
  dir?: string;
33
  gitdir?: string;
34
  message?: string;
35
  author?: PersonObject;
36
  committer?: PersonObject;
37
  signingKey?: string;
38
  onSign?: SignCallback;
39
  amend?: boolean;
40
  dryRun?: boolean;
41
  noUpdateBranch?: boolean;
42
  ref?: string;
43
  parent?: string[];
44
  tree?: string;
45
  cache?: object;
46
}): Promise<string>;
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
import git from "isomorphic-git";
53
import fs from "fs";
54

55
// Basic commit
56
const sha = await git.commit({
57
  fs,
58
  dir: "/path/to/repo",
59
  message: "Add new feature",
60
  author: {
61
    name: "John Doe",
62
    email: "john@example.com"
63
  }
64
});
65
console.log("Created commit:", sha);
66

67
// Commit with custom timestamp
68
await git.commit({
69
  fs,
70
  dir: "/path/to/repo",
71
  message: "Backdate this commit",
72
  author: {
73
    name: "John Doe",
74
    email: "john@example.com",
75
    timestamp: Math.floor(Date.parse("2023-01-01") / 1000)
76
  }
77
});
78

79
// Amend the last commit
80
await git.commit({
81
  fs,
82
  dir: "/path/to/repo",
83
  message: "Updated commit message",
84
  amend: true
85
});
86

87
// Dry run to test commit
88
const wouldCreateSha = await git.commit({
89
  fs,
90
  dir: "/path/to/repo",
91
  message: "Test commit",
92
  author: { name: "Test", email: "test@example.com" },
93
  dryRun: true
94
});
95
```
96

97
### Read Commit History
98

99
Retrieves commit history from the repository.
100

101
```javascript { .api }
102
/**
103
 * Get commit history
104
 * @param args.fs - File system client
105
 * @param args.dir - Working tree directory path
106
 * @param args.gitdir - Git directory path
107
 * @param args.ref - Starting reference (defaults to HEAD)
108
 * @param args.depth - Maximum number of commits to return
109
 * @param args.since - Only commits after this date
110
 * @param args.until - Only commits before this date
111
 * @param args.force - Don't stop on errors
112
 * @param args.follow - Follow file renames
113
 * @param args.cache - Cache object
114
 * @returns Promise resolving to array of commit objects
115
 */
116
function log(args: {
117
  fs: FsClient;
118
  dir?: string;
119
  gitdir?: string;
120
  ref?: string;
121
  depth?: number;
122
  since?: Date;
123
  until?: Date;
124
  force?: boolean;
125
  follow?: boolean;
126
  cache?: object;
127
}): Promise<ReadCommitResult[]>;
128
```
129

130
**Usage Examples:**
131

132
```javascript
133
import git from "isomorphic-git";
134
import fs from "fs";
135

136
// Get last 10 commits
137
const commits = await git.log({
138
  fs,
139
  dir: "/path/to/repo",
140
  depth: 10
141
});
142

143
for (const commit of commits) {
144
  console.log(`${commit.oid.slice(0, 8)} ${commit.commit.message}`);
145
  console.log(`Author: ${commit.commit.author.name} <${commit.commit.author.email}>`);
146
  console.log(`Date: ${new Date(commit.commit.author.timestamp * 1000)}`);
147
  console.log("---");
148
}
149

150
// Get commits from specific branch
151
const branchCommits = await git.log({
152
  fs,
153
  dir: "/path/to/repo",
154
  ref: "feature-branch",
155
  depth: 5
156
});
157

158
// Get commits in date range
159
const recentCommits = await git.log({
160
  fs,
161
  dir: "/path/to/repo",
162
  since: new Date("2023-01-01"),
163
  until: new Date("2023-12-31")
164
});
165
```
166

167
### Read Commit Object
168

169
Reads detailed information about a specific commit.
170

171
```javascript { .api }
172
/**
173
 * Read a commit object
174
 * @param args.fs - File system client
175
 * @param args.dir - Working tree directory path
176
 * @param args.gitdir - Git directory path
177
 * @param args.oid - Commit SHA
178
 * @param args.cache - Cache object
179
 * @returns Promise resolving to commit object
180
 */
181
function readCommit(args: {
182
  fs: FsClient;
183
  dir?: string;
184
  gitdir?: string;
185
  oid: string;
186
  cache?: object;
187
}): Promise<ReadCommitResult>;
188
```
189

190
**Usage Example:**
191

192
```javascript
193
import git from "isomorphic-git";
194
import fs from "fs";
195

196
const commit = await git.readCommit({
197
  fs,
198
  dir: "/path/to/repo",
199
  oid: "abc123..."
200
});
201

202
console.log("Message:", commit.commit.message);
203
console.log("Author:", commit.commit.author.name);
204
console.log("Tree:", commit.commit.tree);
205
console.log("Parents:", commit.commit.parent);
206
```
207

208
### Write Commit Object
209

210
Creates a commit object in the repository.
211

212
```javascript { .api }
213
/**
214
 * Write a commit object
215
 * @param args.fs - File system client
216
 * @param args.dir - Working tree directory path
217
 * @param args.gitdir - Git directory path
218
 * @param args.commit - Commit data
219
 * @returns Promise resolving to commit SHA
220
 */
221
function writeCommit(args: {
222
  fs: FsClient;
223
  dir?: string;
224
  gitdir?: string;
225
  commit: CommitObject;
226
}): Promise<string>;
227
```
228

229
**Usage Example:**
230

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

235
const commitSha = await git.writeCommit({
236
  fs,
237
  dir: "/path/to/repo",
238
  commit: {
239
    message: "Manual commit creation",
240
    tree: "tree-sha-here",
241
    parent: ["parent-commit-sha"],
242
    author: {
243
      name: "Manual Author",
244
      email: "manual@example.com",
245
      timestamp: Math.floor(Date.now() / 1000),
246
      timezoneOffset: new Date().getTimezoneOffset()
247
    },
248
    committer: {
249
      name: "Manual Author", 
250
      email: "manual@example.com",
251
      timestamp: Math.floor(Date.now() / 1000),
252
      timezoneOffset: new Date().getTimezoneOffset()
253
    }
254
  }
255
});
256
```
257

258
### Find Merge Base
259

260
Finds the common ancestor commit between two commits.
261

262
```javascript { .api }
263
/**
264
 * Find the merge base between commits
265
 * @param args.fs - File system client
266
 * @param args.dir - Working tree directory path
267
 * @param args.gitdir - Git directory path
268
 * @param args.oids - Array of commit SHAs to find base for
269
 * @param args.cache - Cache object
270
 * @returns Promise resolving to merge base commit SHA
271
 */
272
function findMergeBase(args: {
273
  fs: FsClient;
274
  dir?: string;
275
  gitdir?: string;
276
  oids: string[];
277
  cache?: object;
278
}): Promise<string[]>;
279
```
280

281
**Usage Example:**
282

283
```javascript
284
import git from "isomorphic-git";
285
import fs from "fs";
286

287
const mergeBase = await git.findMergeBase({
288
  fs,
289
  dir: "/path/to/repo",
290
  oids: ["commit-sha-1", "commit-sha-2"]
291
});
292
console.log("Merge base:", mergeBase[0]);
293
```
294

295
### Check Descendant Relationship
296

297
Checks if one commit is a descendant of another.
298

299
```javascript { .api }
300
/**
301
 * Check if one commit is descendant of another
302
 * @param args.fs - File system client
303
 * @param args.dir - Working tree directory path
304
 * @param args.gitdir - Git directory path
305
 * @param args.oid - Potential descendant commit SHA
306
 * @param args.ancestor - Potential ancestor commit SHA
307
 * @param args.depth - Maximum depth to search
308
 * @param args.cache - Cache object
309
 * @returns Promise resolving to true if descendant relationship exists
310
 */
311
function isDescendent(args: {
312
  fs: FsClient;
313
  dir?: string;
314
  gitdir?: string;
315
  oid: string;
316
  ancestor: string;
317
  depth?: number;
318
  cache?: object;
319
}): Promise<boolean>;
320
```
321

322
**Usage Example:**
323

324
```javascript
325
import git from "isomorphic-git";
326
import fs from "fs";
327

328
const isDesc = await git.isDescendent({
329
  fs,
330
  dir: "/path/to/repo",
331
  oid: "newer-commit-sha",
332
  ancestor: "older-commit-sha"
333
});
334
console.log(isDesc ? "Is descendant" : "Not descendant");
335
```
336

337
## Types
338

339
```javascript { .api }
340
interface PersonObject {
341
  name?: string;
342
  email?: string;
343
  timestamp?: number;
344
  timezoneOffset?: number;
345
}
346

347
interface CommitObject {
348
  message: string;
349
  tree: string;
350
  parent: string[];
351
  author: PersonObject;
352
  committer: PersonObject;
353
  gpgsig?: string;
354
}
355

356
interface ReadCommitResult {
357
  oid: string;
358
  commit: CommitObject;
359
  payload: string;
360
}
361

362
type SignCallback = (args: {
363
  payload: string;
364
  secretKey: string;
365
}) => string | Promise<string>;
366
```