]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
5e0de328 | 2 | * Copyright (C) 2009-2012 the libgit2 contributors |
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 | * | |
1795f879 | 66 | * @param walker 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 | */ |
1795f879 | 70 | GIT_EXTERN(int) git_revwalk_new(git_revwalk **walker, 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 | |
95 | * must be pushed the repository before a walk can | |
96 | * be started. | |
3315782c | 97 | * |
d144c569 | 98 | * @param walk the walker being used for the traversal. |
36aaf1ff | 99 | * @param oid the oid of the commit to start from. |
e172cf08 | 100 | * @return 0 or an error code |
06160502 | 101 | */ |
71db842f VM |
102 | GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *oid); |
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 | * | |
110 | * A leading 'refs/' is implied it not present as well as a trailing | |
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 VM |
136 | * @param walk the walker being used for the traversal. |
137 | * @param oid the oid of commit that will be ignored during the traversal | |
e172cf08 | 138 | * @return 0 or an error code |
06160502 | 139 | */ |
71db842f | 140 | GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *oid); |
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 | * | |
149 | * A leading 'refs/' is implied it not present as well as a trailing | |
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 | * | |
201 | * @param oid Pointer where to store the oid of the next commit | |
3315782c | 202 | * @param walk the walker to pop the commit from. |
e172cf08 VM |
203 | * @return 0 if the next commit was found; |
204 | * GIT_REVWALKOVER if there are no commits left to iterate | |
06160502 | 205 | */ |
71db842f | 206 | GIT_EXTERN(int) git_revwalk_next(git_oid *oid, 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 | |
06160502 | 219 | /** |
36aaf1ff VM |
220 | * Free a revision walker previously allocated. |
221 | * | |
87d9869f | 222 | * @param walk traversal handle to close. If NULL nothing occurs. |
06160502 | 223 | */ |
3315782c | 224 | GIT_EXTERN(void) git_revwalk_free(git_revwalk *walk); |
06160502 | 225 | |
a13bc8e7 VM |
226 | /** |
227 | * Return the repository on which this walker | |
228 | * is operating. | |
229 | * | |
230 | * @param walk the revision walker | |
231 | * @return the repository being walked | |
232 | */ | |
233 | GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk); | |
234 | ||
06160502 SP |
235 | /** @} */ |
236 | GIT_END_DECL | |
237 | #endif |