0
# Commit History Traversal
1

2
Comprehensive commit history traversal and navigation using the Revwalk class. Provides efficient algorithms for walking commit graphs, filtering commits, and analyzing repository history.
3

4
## Core Imports
5

6
```javascript
7
const NodeGit = require('nodegit');
8
const Revwalk = NodeGit.Revwalk;
9
```
10

11
## Capabilities
12

13
### Revision Walker Creation
14

15
Create and configure revision walkers for traversing commit history.
16

17
```javascript { .api }
18
/**
19
 * Create a new revision walker for the repository
20
 * @param {Repository} repo - Repository to walk
21
 * @returns {Revwalk} New revision walker instance
22
 */
23
Revwalk.create(repo): Revwalk;
24
```
25

26
### Traversal Configuration
27

28
Configure how the revision walker traverses commit history.
29

30
```javascript { .api }
31
/**
32
 * Set the sort order for the revwalk. Accepts multiple sort flags.
33
 * @param {Number} sort - Sort flags (can be combined with bitwise OR)
34
 */
35
sorting(...sorts): void;
36

37
/**
38
 * Push one or more commit OIDs to start the walk from
39
 * @param {Oid} oid - Commit OID to start from
40
 */
41
push(oid): void;
42

43
/**
44
 * Push the repository HEAD
45
 */
46
pushHead(): void;
47

48
/**
49
 * Push all references in the repository
50
 */
51
pushGlob(glob): void;
52

53
/**
54
 * Push all references matching a pattern
55
 * @param {String} pattern - Reference pattern to match
56
 */
57
pushRef(pattern): void;
58

59
/**
60
 * Hide a commit and its ancestors from the walk
61
 * @param {Oid} oid - Commit OID to hide
62
 */
63
hide(oid): void;
64

65
/**
66
 * Hide the repository HEAD and its ancestors
67
 */
68
hideHead(): void;
69

70
/**
71
 * Hide all references matching a pattern
72
 * @param {String} pattern - Reference pattern to hide
73
 */
74
hideRef(pattern): void;
75
```
76

77
### Enhanced Walking Methods
78

79
Convenient methods for common traversal patterns.
80

81
```javascript { .api }
82
/**
83
 * Get a specific number of commits from the walk
84
 * @param {Number} count - Number of commits to retrieve (default: 10)
85
 * @returns {Promise<Commit[]>} Array of commits
86
 */
87
getCommits(count): Promise<Commit[]>;
88

89
/**
90
 * Walk commits until a condition is met
91
 * @param {Function} checkFn - Function that returns false to stop walking
92
 * @returns {Promise<Commit[]>} Array of commits collected
93
 */
94
getCommitsUntil(checkFn): Promise<Commit[]>;
95

96
/**
97
 * Walk the history of a specific file
98
 * @param {String} filePath - Path to the file
99
 * @param {Number} maxCount - Maximum number of entries to return
100
 * @returns {Promise<HistoryEntry[]>} File history entries
101
 */
102
fileHistoryWalk(filePath, maxCount): Promise<HistoryEntry[]>;
103

104
/**
105
 * Walk commits with a callback function
106
 * @param {Oid} oid - Starting commit OID
107
 * @param {Function} callback - Function called for each commit
108
 */
109
walk(oid, callback): void;
110
```
111

112
### Basic Navigation
113

114
Core methods for stepping through commit history.
115

116
```javascript { .api }
117
/**
118
 * Get the next commit OID in the walk
119
 * @returns {Promise<Oid>} Next commit OID, or null if done
120
 */
121
next(): Promise<Oid>;
122

123
/**
124
 * Reset the walker to start over
125
 */
126
reset(): void;
127

128
/**
129
 * Get the repository associated with this walker
130
 * @returns {Repository} The repository
131
 */
132
repository(): Repository;
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
const NodeGit = require('nodegit');
139

140
// Get the last 20 commits from HEAD
141
NodeGit.Repository.open('./my-repo')
142
  .then(repo => {
143
    return repo.createRevWalk();
144
  })
145
  .then(walker => {
146
    walker.pushHead();
147
    walker.sorting(NodeGit.Revwalk.SORT.TIME);
148
    return walker.getCommits(20);
149
  })
150
  .then(commits => {
151
    commits.forEach(commit => {
152
      console.log(`${commit.sha().substring(0, 8)} - ${commit.message().trim()}`);
153
    });
154
  });
155

156
// Walk commits between two points
157
NodeGit.Repository.open('./my-repo')
158
  .then(repo => {
159
    const walker = repo.createRevWalk();
160
    walker.push('HEAD');
161
    walker.hide('origin/main');
162
    return walker.getCommits(100);
163
  })
164
  .then(commits => {
165
    console.log(`Found ${commits.length} commits ahead of origin/main`);
166
  });
167

168
// Track file history
169
NodeGit.Repository.open('./my-repo')
170
  .then(repo => {
171
    const walker = repo.createRevWalk();
172
    walker.pushHead();
173
    return walker.fileHistoryWalk('src/index.js', 50);
174
  })
175
  .then(history => {
176
    history.forEach(entry => {
177
      console.log(`Commit ${entry.commit.sha()} - ${entry.status} - ${entry.newName || entry.oldName}`);
178
    });
179
  });
180
```
181

182
## Types
183

184
```javascript { .api }
185
interface HistoryEntry {
186
  /** The commit for this history entry */
187
  commit: Commit;
188
  /** Status of the file in this commit */
189
  status: number;
190
  /** New filename (when renamed) */
191
  newName?: string;
192
  /** Old filename (when renamed) */
193
  oldName?: string;
194
}
195
```
196

197
## Sort Options
198

199
```javascript { .api }
200
Revwalk.SORT = {
201
  /** Do not sort commits, use default ordering */
202
  NONE: 0,
203
  /** Sort commits in topological order */
204
  TOPOLOGICAL: 1,
205
  /** Sort commits by commit time */
206
  TIME: 2,
207
  /** Reverse the sorting order */
208
  REVERSE: 4
209
};
210
```