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 /** @} */