]>
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 | /** |
3315782c | 24 | * Sort the repository contents in no particular ordering; |
0037e491 | 25 | * this sorting is arbitrary, implementation-specific |
e5d1faef | 26 | * and subject to change at any time. |
3315782c | 27 | * This is the default sorting for new walkers. |
e5d1faef | 28 | */ |
87d9869f | 29 | #define GIT_SORT_NONE (0) |
e5d1faef VM |
30 | |
31 | /** | |
3315782c | 32 | * Sort the repository contents in topological order |
e5d1faef VM |
33 | * (parents before children); this sorting mode |
34 | * can be combined with time sorting. | |
35 | */ | |
87d9869f | 36 | #define GIT_SORT_TOPOLOGICAL (1 << 0) |
e5d1faef VM |
37 | |
38 | /** | |
3315782c | 39 | * Sort the repository contents by commit time; |
e5d1faef VM |
40 | * this sorting mode can be combined with |
41 | * topological sorting. | |
42 | */ | |
87d9869f | 43 | #define GIT_SORT_TIME (1 << 1) |
e5d1faef VM |
44 | |
45 | /** | |
3315782c | 46 | * Iterate through the repository contents in reverse |
e5d1faef VM |
47 | * order; this sorting mode can be combined with |
48 | * any of the above. | |
49 | */ | |
87d9869f | 50 | #define GIT_SORT_REVERSE (1 << 2) |
3315782c | 51 | |
06160502 | 52 | /** |
3315782c | 53 | * Allocate a new revision walker to iterate through a repo. |
06160502 | 54 | * |
36aaf1ff VM |
55 | * This revision walker uses a custom memory pool and an internal |
56 | * commit cache, so it is relatively expensive to allocate. | |
57 | * | |
58 | * For maximum performance, this revision walker should be | |
59 | * reused for different walks. | |
60 | * | |
61 | * This revision walker is *not* thread safe: it may only be | |
62 | * used to walk a repository on a single thread; however, | |
63 | * it is possible to have several revision walkers in | |
64 | * several different threads walking the same repository. | |
65 | * | |
44d9f2cb | 66 | * @param out pointer to the new revision walker |
3315782c | 67 | * @param repo the repo to walk through |
e172cf08 | 68 | * @return 0 or an error code |
06160502 | 69 | */ |
44d9f2cb | 70 | GIT_EXTERN(int) git_revwalk_new(git_revwalk **out, git_repository *repo); |
06160502 SP |
71 | |
72 | /** | |
36aaf1ff VM |
73 | * Reset the revision walker for reuse. |
74 | * | |
75 | * This will clear all the pushed and hidden commits, and | |
76 | * leave the walker in a blank state (just like at | |
77 | * creation) ready to receive new commit pushes and | |
78 | * start a new walk. | |
79 | * | |
80 | * The revision walk is automatically reset when a walk | |
81 | * is over. | |
82 | * | |
3315782c | 83 | * @param walker handle to reset. |
06160502 | 84 | */ |
3315782c | 85 | GIT_EXTERN(void) git_revwalk_reset(git_revwalk *walker); |
06160502 SP |
86 | |
87 | /** | |
3315782c | 88 | * Mark a commit to start traversal from. |
36aaf1ff VM |
89 | * |
90 | * The given OID must belong to a commit on the walked | |
91 | * repository. | |
92 | * | |
93 | * The given commit will be used as one of the roots | |
94 | * when starting the revision walk. At least one commit | |
804c5f56 | 95 | * must be pushed onto the walker before a walk can |
36aaf1ff | 96 | * be started. |
3315782c | 97 | * |
d144c569 | 98 | * @param walk the walker being used for the traversal. |
44d9f2cb | 99 | * @param id the oid of the commit to start from. |
e172cf08 | 100 | * @return 0 or an error code |
06160502 | 101 | */ |
44d9f2cb | 102 | GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *id); |
71db842f | 103 | |
155aca2d CMN |
104 | /** |
105 | * Push matching references | |
106 | * | |
d73c94b2 | 107 | * The OIDs pointed to by the references that match the given glob |
155aca2d CMN |
108 | * pattern will be pushed to the revision walker. |
109 | * | |
4ea7c8c6 | 110 | * A leading 'refs/' is implied if not present as well as a trailing |
155aca2d CMN |
111 | * '/ *' if the glob lacks '?', '*' or '['. |
112 | * | |
113 | * @param walk the walker being used for the traversal | |
114 | * @param glob the glob pattern references should match | |
e172cf08 | 115 | * @return 0 or an error code |
155aca2d CMN |
116 | */ |
117 | GIT_EXTERN(int) git_revwalk_push_glob(git_revwalk *walk, const char *glob); | |
06160502 | 118 | |
f7367993 CMN |
119 | /** |
120 | * Push the repository's HEAD | |
121 | * | |
122 | * @param walk the walker being used for the traversal | |
e172cf08 | 123 | * @return 0 or an error code |
f7367993 CMN |
124 | */ |
125 | GIT_EXTERN(int) git_revwalk_push_head(git_revwalk *walk); | |
126 | ||
06160502 SP |
127 | /** |
128 | * Mark a commit (and its ancestors) uninteresting for the output. | |
36aaf1ff VM |
129 | * |
130 | * The given OID must belong to a commit on the walked | |
131 | * repository. | |
132 | * | |
133 | * The resolved commit and all its parents will be hidden from the | |
134 | * output on the revision walk. | |
135 | * | |
d144c569 | 136 | * @param walk the walker being used for the traversal. |
44d9f2cb | 137 | * @param commit_id the oid of commit that will be ignored during the traversal |
e172cf08 | 138 | * @return 0 or an error code |
06160502 | 139 | */ |
44d9f2cb | 140 | GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *commit_id); |
06160502 | 141 | |
155aca2d CMN |
142 | /** |
143 | * Hide matching references. | |
144 | * | |
d73c94b2 | 145 | * The OIDs pointed to by the references that match the given glob |
155aca2d CMN |
146 | * pattern and their ancestors will be hidden from the output on the |
147 | * revision walk. | |
148 | * | |
4ea7c8c6 | 149 | * A leading 'refs/' is implied if not present as well as a trailing |
155aca2d CMN |
150 | * '/ *' if the glob lacks '?', '*' or '['. |
151 | * | |
152 | * @param walk the walker being used for the traversal | |
153 | * @param glob the glob pattern references should match | |
e172cf08 | 154 | * @return 0 or an error code |
155aca2d CMN |
155 | */ |
156 | GIT_EXTERN(int) git_revwalk_hide_glob(git_revwalk *walk, const char *glob); | |
157 | ||
f7367993 CMN |
158 | /** |
159 | * Hide the repository's HEAD | |
160 | * | |
161 | * @param walk the walker being used for the traversal | |
e172cf08 | 162 | * @return 0 or an error code |
f7367993 CMN |
163 | */ |
164 | GIT_EXTERN(int) git_revwalk_hide_head(git_revwalk *walk); | |
165 | ||
06b9d915 CMN |
166 | /** |
167 | * Push the OID pointed to by a reference | |
168 | * | |
169 | * The reference must point to a commit. | |
170 | * | |
171 | * @param walk the walker being used for the traversal | |
d73c94b2 | 172 | * @param refname the reference to push |
e172cf08 | 173 | * @return 0 or an error code |
06b9d915 CMN |
174 | */ |
175 | GIT_EXTERN(int) git_revwalk_push_ref(git_revwalk *walk, const char *refname); | |
176 | ||
177 | /** | |
178 | * Hide the OID pointed to by a reference | |
179 | * | |
180 | * The reference must point to a commit. | |
181 | * | |
182 | * @param walk the walker being used for the traversal | |
d73c94b2 | 183 | * @param refname the reference to hide |
e172cf08 | 184 | * @return 0 or an error code |
06b9d915 CMN |
185 | */ |
186 | GIT_EXTERN(int) git_revwalk_hide_ref(git_revwalk *walk, const char *refname); | |
187 | ||
06160502 | 188 | /** |
36aaf1ff VM |
189 | * Get the next commit from the revision walk. |
190 | * | |
191 | * The initial call to this method is *not* blocking when | |
192 | * iterating through a repo with a time-sorting mode. | |
193 | * | |
194 | * Iterating with Topological or inverted modes makes the initial | |
195 | * call blocking to preprocess the commit list, but this block should be | |
196 | * mostly unnoticeable on most repositories (topological preprocessing | |
197 | * times at 0.3s on the git.git repo). | |
c836c332 | 198 | * |
36aaf1ff VM |
199 | * The revision walker is reset when the walk is over. |
200 | * | |
44d9f2cb | 201 | * @param out Pointer where to store the oid of the next commit |
3315782c | 202 | * @param walk the walker to pop the commit from. |
e172cf08 | 203 | * @return 0 if the next commit was found; |
f335ecd6 | 204 | * GIT_ITEROVER if there are no commits left to iterate |
06160502 | 205 | */ |
44d9f2cb | 206 | GIT_EXTERN(int) git_revwalk_next(git_oid *out, git_revwalk *walk); |
06160502 | 207 | |
e5d1faef VM |
208 | /** |
209 | * Change the sorting mode when iterating through the | |
3315782c | 210 | * repository's contents. |
36aaf1ff | 211 | * |
3315782c | 212 | * Changing the sorting mode resets the walker. |
36aaf1ff | 213 | * |
3315782c | 214 | * @param walk the walker being used for the traversal. |
36aaf1ff | 215 | * @param sort_mode combination of GIT_SORT_XXX flags |
e5d1faef | 216 | */ |
36aaf1ff | 217 | GIT_EXTERN(void) git_revwalk_sorting(git_revwalk *walk, unsigned int sort_mode); |
e5d1faef | 218 | |
af079d8b GP |
219 | /** |
220 | * Push and hide the respective endpoints of the given range. | |
221 | * | |
222 | * The range should be of the form | |
223 | * <commit>..<commit> | |
224 | * where each <commit> is in the form accepted by 'git_revparse_single'. | |
225 | * The left-hand commit will be hidden and the right-hand commit pushed. | |
226 | * | |
227 | * @param walk the walker being used for the traversal | |
228 | * @param range the range | |
229 | * @return 0 or an error code | |
230 | * | |
231 | */ | |
232 | GIT_EXTERN(int) git_revwalk_push_range(git_revwalk *walk, const char *range); | |
233 | ||
15f7b9b8 CMN |
234 | /** |
235 | * Simplify the history by first-parent | |
236 | * | |
237 | * No parents other than the first for each commit will be enqueued. | |
238 | */ | |
239 | GIT_EXTERN(void) git_revwalk_simplify_first_parent(git_revwalk *walk); | |
240 | ||
241 | ||
06160502 | 242 | /** |
36aaf1ff VM |
243 | * Free a revision walker previously allocated. |
244 | * | |
87d9869f | 245 | * @param walk traversal handle to close. If NULL nothing occurs. |
06160502 | 246 | */ |
3315782c | 247 | GIT_EXTERN(void) git_revwalk_free(git_revwalk *walk); |
06160502 | 248 | |
a13bc8e7 VM |
249 | /** |
250 | * Return the repository on which this walker | |
251 | * is operating. | |
252 | * | |
253 | * @param walk the revision walker | |
254 | * @return the repository being walked | |
255 | */ | |
256 | GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk); | |
257 | ||
06160502 SP |
258 | /** @} */ |
259 | GIT_END_DECL | |
260 | #endif |