]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
f5918330 | 3 | * |
bb742ede VM |
4 | * This file is part of libgit2, distributed under the GNU GPL v2 with |
5 | * a Linking Exception. For full terms see the included COPYING file. | |
f5918330 | 6 | */ |
06160502 SP |
7 | #ifndef INCLUDE_git_revwalk_h__ |
8 | #define INCLUDE_git_revwalk_h__ | |
9 | ||
257bd746 | 10 | #include "common.h" |
d12299fe | 11 | #include "types.h" |
b5c5f0f8 | 12 | #include "oid.h" |
06160502 SP |
13 | |
14 | /** | |
f5918330 | 15 | * @file git2/revwalk.h |
06160502 SP |
16 | * @brief Git revision traversal routines |
17 | * @defgroup git_revwalk Git revision traversal routines | |
18 | * @ingroup Git | |
19 | * @{ | |
20 | */ | |
21 | GIT_BEGIN_DECL | |
22 | ||
e5d1faef | 23 | /** |
12e18031 | 24 | * Flags to specify the sorting which a revwalk should perform. |
e5d1faef | 25 | */ |
12e18031 CMN |
26 | typedef enum { |
27 | /** | |
ac3d33df JK |
28 | * Sort the output with the same default method from `git`: reverse |
29 | * chronological order. This is the default sorting for new walkers. | |
12e18031 CMN |
30 | */ |
31 | GIT_SORT_NONE = 0, | |
e5d1faef | 32 | |
12e18031 | 33 | /** |
ac3d33df JK |
34 | * Sort the repository contents in topological order (no parents before |
35 | * all of its children are shown); this sorting mode can be combined | |
36 | * with time sorting to produce `git`'s `--date-order``. | |
12e18031 CMN |
37 | */ |
38 | GIT_SORT_TOPOLOGICAL = 1 << 0, | |
e5d1faef | 39 | |
12e18031 CMN |
40 | /** |
41 | * Sort the repository contents by commit time; | |
42 | * this sorting mode can be combined with | |
43 | * topological sorting. | |
44 | */ | |
45 | GIT_SORT_TIME = 1 << 1, | |
e5d1faef | 46 | |
12e18031 CMN |
47 | /** |
48 | * Iterate through the repository contents in reverse | |
49 | * order; this sorting mode can be combined with | |
50 | * any of the above. | |
51 | */ | |
e579e0f7 | 52 | GIT_SORT_REVERSE = 1 << 2 |
12e18031 | 53 | } git_sort_t; |
3315782c | 54 | |
06160502 | 55 | /** |
3315782c | 56 | * Allocate a new revision walker to iterate through a repo. |
06160502 | 57 | * |
36aaf1ff VM |
58 | * This revision walker uses a custom memory pool and an internal |
59 | * commit cache, so it is relatively expensive to allocate. | |
60 | * | |
61 | * For maximum performance, this revision walker should be | |
62 | * reused for different walks. | |
63 | * | |
64 | * This revision walker is *not* thread safe: it may only be | |
65 | * used to walk a repository on a single thread; however, | |
66 | * it is possible to have several revision walkers in | |
67 | * several different threads walking the same repository. | |
68 | * | |
44d9f2cb | 69 | * @param out pointer to the new revision walker |
3315782c | 70 | * @param repo the repo to walk through |
e172cf08 | 71 | * @return 0 or an error code |
06160502 | 72 | */ |
44d9f2cb | 73 | GIT_EXTERN(int) git_revwalk_new(git_revwalk **out, git_repository *repo); |
06160502 SP |
74 | |
75 | /** | |
36aaf1ff VM |
76 | * Reset the revision walker for reuse. |
77 | * | |
78 | * This will clear all the pushed and hidden commits, and | |
79 | * leave the walker in a blank state (just like at | |
80 | * creation) ready to receive new commit pushes and | |
81 | * start a new walk. | |
82 | * | |
83 | * The revision walk is automatically reset when a walk | |
84 | * is over. | |
85 | * | |
3315782c | 86 | * @param walker handle to reset. |
22a2d3d5 | 87 | * @return 0 or an error code |
06160502 | 88 | */ |
22a2d3d5 | 89 | GIT_EXTERN(int) git_revwalk_reset(git_revwalk *walker); |
06160502 SP |
90 | |
91 | /** | |
05d92026 | 92 | * Add a new root for the traversal |
36aaf1ff | 93 | * |
05d92026 CMN |
94 | * The pushed commit will be marked as one of the roots from which to |
95 | * start the walk. This commit may not be walked if it or a child is | |
96 | * hidden. | |
97 | * | |
98 | * At least one commit must be pushed onto the walker before a walk | |
99 | * can be started. | |
36aaf1ff | 100 | * |
05d92026 CMN |
101 | * The given id must belong to a committish on the walked |
102 | * repository. | |
3315782c | 103 | * |
d144c569 | 104 | * @param walk the walker being used for the traversal. |
44d9f2cb | 105 | * @param id the oid of the commit to start from. |
e172cf08 | 106 | * @return 0 or an error code |
06160502 | 107 | */ |
44d9f2cb | 108 | GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *id); |
71db842f | 109 | |
155aca2d CMN |
110 | /** |
111 | * Push matching references | |
112 | * | |
d73c94b2 | 113 | * The OIDs pointed to by the references that match the given glob |
155aca2d CMN |
114 | * pattern will be pushed to the revision walker. |
115 | * | |
4ea7c8c6 | 116 | * A leading 'refs/' is implied if not present as well as a trailing |
d6006413 | 117 | * '/\*' if the glob lacks '?', '\*' or '['. |
155aca2d | 118 | * |
d465e4e9 CMN |
119 | * Any references matching this glob which do not point to a |
120 | * committish will be ignored. | |
121 | * | |
155aca2d CMN |
122 | * @param walk the walker being used for the traversal |
123 | * @param glob the glob pattern references should match | |
e172cf08 | 124 | * @return 0 or an error code |
155aca2d CMN |
125 | */ |
126 | GIT_EXTERN(int) git_revwalk_push_glob(git_revwalk *walk, const char *glob); | |
06160502 | 127 | |
f7367993 CMN |
128 | /** |
129 | * Push the repository's HEAD | |
130 | * | |
131 | * @param walk the walker being used for the traversal | |
e172cf08 | 132 | * @return 0 or an error code |
f7367993 CMN |
133 | */ |
134 | GIT_EXTERN(int) git_revwalk_push_head(git_revwalk *walk); | |
135 | ||
06160502 SP |
136 | /** |
137 | * Mark a commit (and its ancestors) uninteresting for the output. | |
36aaf1ff | 138 | * |
05d92026 | 139 | * The given id must belong to a committish on the walked |
36aaf1ff VM |
140 | * repository. |
141 | * | |
142 | * The resolved commit and all its parents will be hidden from the | |
143 | * output on the revision walk. | |
144 | * | |
d144c569 | 145 | * @param walk the walker being used for the traversal. |
44d9f2cb | 146 | * @param commit_id the oid of commit that will be ignored during the traversal |
e172cf08 | 147 | * @return 0 or an error code |
06160502 | 148 | */ |
44d9f2cb | 149 | GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *commit_id); |
06160502 | 150 | |
155aca2d CMN |
151 | /** |
152 | * Hide matching references. | |
153 | * | |
d73c94b2 | 154 | * The OIDs pointed to by the references that match the given glob |
155aca2d CMN |
155 | * pattern and their ancestors will be hidden from the output on the |
156 | * revision walk. | |
157 | * | |
4ea7c8c6 | 158 | * A leading 'refs/' is implied if not present as well as a trailing |
d6006413 | 159 | * '/\*' if the glob lacks '?', '\*' or '['. |
155aca2d | 160 | * |
d465e4e9 CMN |
161 | * Any references matching this glob which do not point to a |
162 | * committish will be ignored. | |
163 | * | |
155aca2d CMN |
164 | * @param walk the walker being used for the traversal |
165 | * @param glob the glob pattern references should match | |
e172cf08 | 166 | * @return 0 or an error code |
155aca2d CMN |
167 | */ |
168 | GIT_EXTERN(int) git_revwalk_hide_glob(git_revwalk *walk, const char *glob); | |
169 | ||
f7367993 CMN |
170 | /** |
171 | * Hide the repository's HEAD | |
172 | * | |
173 | * @param walk the walker being used for the traversal | |
e172cf08 | 174 | * @return 0 or an error code |
f7367993 CMN |
175 | */ |
176 | GIT_EXTERN(int) git_revwalk_hide_head(git_revwalk *walk); | |
177 | ||
06b9d915 CMN |
178 | /** |
179 | * Push the OID pointed to by a reference | |
180 | * | |
f61272e0 | 181 | * The reference must point to a committish. |
06b9d915 CMN |
182 | * |
183 | * @param walk the walker being used for the traversal | |
d73c94b2 | 184 | * @param refname the reference to push |
e172cf08 | 185 | * @return 0 or an error code |
06b9d915 CMN |
186 | */ |
187 | GIT_EXTERN(int) git_revwalk_push_ref(git_revwalk *walk, const char *refname); | |
188 | ||
189 | /** | |
190 | * Hide the OID pointed to by a reference | |
191 | * | |
f61272e0 | 192 | * The reference must point to a committish. |
06b9d915 CMN |
193 | * |
194 | * @param walk the walker being used for the traversal | |
d73c94b2 | 195 | * @param refname the reference to hide |
e172cf08 | 196 | * @return 0 or an error code |
06b9d915 CMN |
197 | */ |
198 | GIT_EXTERN(int) git_revwalk_hide_ref(git_revwalk *walk, const char *refname); | |
199 | ||
06160502 | 200 | /** |
36aaf1ff VM |
201 | * Get the next commit from the revision walk. |
202 | * | |
203 | * The initial call to this method is *not* blocking when | |
204 | * iterating through a repo with a time-sorting mode. | |
205 | * | |
206 | * Iterating with Topological or inverted modes makes the initial | |
207 | * call blocking to preprocess the commit list, but this block should be | |
208 | * mostly unnoticeable on most repositories (topological preprocessing | |
209 | * times at 0.3s on the git.git repo). | |
c836c332 | 210 | * |
36aaf1ff VM |
211 | * The revision walker is reset when the walk is over. |
212 | * | |
44d9f2cb | 213 | * @param out Pointer where to store the oid of the next commit |
3315782c | 214 | * @param walk the walker to pop the commit from. |
e172cf08 | 215 | * @return 0 if the next commit was found; |
f335ecd6 | 216 | * GIT_ITEROVER if there are no commits left to iterate |
06160502 | 217 | */ |
44d9f2cb | 218 | GIT_EXTERN(int) git_revwalk_next(git_oid *out, git_revwalk *walk); |
06160502 | 219 | |
e5d1faef VM |
220 | /** |
221 | * Change the sorting mode when iterating through the | |
3315782c | 222 | * repository's contents. |
36aaf1ff | 223 | * |
3315782c | 224 | * Changing the sorting mode resets the walker. |
36aaf1ff | 225 | * |
3315782c | 226 | * @param walk the walker being used for the traversal. |
36aaf1ff | 227 | * @param sort_mode combination of GIT_SORT_XXX flags |
22a2d3d5 | 228 | * @return 0 or an error code |
e5d1faef | 229 | */ |
22a2d3d5 | 230 | GIT_EXTERN(int) git_revwalk_sorting(git_revwalk *walk, unsigned int sort_mode); |
e5d1faef | 231 | |
af079d8b GP |
232 | /** |
233 | * Push and hide the respective endpoints of the given range. | |
234 | * | |
235 | * The range should be of the form | |
236 | * <commit>..<commit> | |
237 | * where each <commit> is in the form accepted by 'git_revparse_single'. | |
238 | * The left-hand commit will be hidden and the right-hand commit pushed. | |
239 | * | |
240 | * @param walk the walker being used for the traversal | |
241 | * @param range the range | |
242 | * @return 0 or an error code | |
243 | * | |
244 | */ | |
245 | GIT_EXTERN(int) git_revwalk_push_range(git_revwalk *walk, const char *range); | |
246 | ||
15f7b9b8 CMN |
247 | /** |
248 | * Simplify the history by first-parent | |
249 | * | |
250 | * No parents other than the first for each commit will be enqueued. | |
22a2d3d5 | 251 | * |
e579e0f7 | 252 | * @param walk The revision walker. |
22a2d3d5 | 253 | * @return 0 or an error code |
15f7b9b8 | 254 | */ |
22a2d3d5 | 255 | GIT_EXTERN(int) git_revwalk_simplify_first_parent(git_revwalk *walk); |
15f7b9b8 CMN |
256 | |
257 | ||
06160502 | 258 | /** |
36aaf1ff VM |
259 | * Free a revision walker previously allocated. |
260 | * | |
87d9869f | 261 | * @param walk traversal handle to close. If NULL nothing occurs. |
06160502 | 262 | */ |
3315782c | 263 | GIT_EXTERN(void) git_revwalk_free(git_revwalk *walk); |
06160502 | 264 | |
a13bc8e7 VM |
265 | /** |
266 | * Return the repository on which this walker | |
267 | * is operating. | |
268 | * | |
269 | * @param walk the revision walker | |
270 | * @return the repository being walked | |
271 | */ | |
272 | GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk); | |
273 | ||
892aa808 | 274 | /** |
892b7c9f AG |
275 | * This is a callback function that user can provide to hide a |
276 | * commit and its parents. If the callback function returns non-zero value, | |
277 | * then this commit and its parents will be hidden. | |
278 | * | |
279 | * @param commit_id oid of Commit | |
280 | * @param payload User-specified pointer to data to be passed as data payload | |
e579e0f7 | 281 | * @return non-zero to hide the commmit and it parent. |
892b7c9f | 282 | */ |
ac3d33df | 283 | typedef int GIT_CALLBACK(git_revwalk_hide_cb)( |
892aa808 AG |
284 | const git_oid *commit_id, |
285 | void *payload); | |
286 | ||
287 | /** | |
ac3d33df | 288 | * Adds, changes or removes a callback function to hide a commit and its parents |
892b7c9f AG |
289 | * |
290 | * @param walk the revision walker | |
291 | * @param hide_cb callback function to hide a commit and its parents | |
292 | * @param payload data payload to be passed to callback function | |
e579e0f7 | 293 | * @return 0 or an error code. |
892b7c9f | 294 | */ |
892aa808 AG |
295 | GIT_EXTERN(int) git_revwalk_add_hide_cb( |
296 | git_revwalk *walk, | |
297 | git_revwalk_hide_cb hide_cb, | |
298 | void *payload); | |
299 | ||
06160502 SP |
300 | /** @} */ |
301 | GIT_END_DECL | |
302 | #endif |