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