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 #ifndef INCLUDE_git_revwalk_h__ 8 #define INCLUDE_git_revwalk_h__ 9 10 #include "common.h" 11 #include "types.h" 12 #include "oid.h" 13 14 /** 15 * @file git2/revwalk.h 16 * @brief Git revision traversal routines 17 * @defgroup git_revwalk Git revision traversal routines 18 * @ingroup Git 19 * @{ 20 */ 21 GIT_BEGIN_DECL 22 23 /** 24 * Flags to specify the sorting which a revwalk should perform. 25 */ 26 typedef enum { 27 /** 28 * Sort the output with the same default method from `git`: reverse 29 * chronological order. This is the default sorting for new walkers. 30 */ 31 GIT_SORT_NONE = 0, 32 33 /** 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``. 37 */ 38 GIT_SORT_TOPOLOGICAL = 1 << 0, 39 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, 46 47 /** 48 * Iterate through the repository contents in reverse 49 * order; this sorting mode can be combined with 50 * any of the above. 51 */ 52 GIT_SORT_REVERSE = 1 << 2, 53 } git_sort_t; 54 55 /** 56 * Allocate a new revision walker to iterate through a repo. 57 * 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 * 69 * @param out pointer to the new revision walker 70 * @param repo the repo to walk through 71 * @return 0 or an error code 72 */ 73 GIT_EXTERN(int) git_revwalk_new(git_revwalk **out, git_repository *repo); 74 75 /** 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 * 86 * @param walker handle to reset. 87 * @return 0 or an error code 88 */ 89 GIT_EXTERN(int) git_revwalk_reset(git_revwalk *walker); 90 91 /** 92 * Add a new root for the traversal 93 * 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. 100 * 101 * The given id must belong to a committish on the walked 102 * repository. 103 * 104 * @param walk the walker being used for the traversal. 105 * @param id the oid of the commit to start from. 106 * @return 0 or an error code 107 */ 108 GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *id); 109 110 /** 111 * Push matching references 112 * 113 * The OIDs pointed to by the references that match the given glob 114 * pattern will be pushed to the revision walker. 115 * 116 * A leading 'refs/' is implied if not present as well as a trailing 117 * '/\*' if the glob lacks '?', '\*' or '['. 118 * 119 * Any references matching this glob which do not point to a 120 * committish will be ignored. 121 * 122 * @param walk the walker being used for the traversal 123 * @param glob the glob pattern references should match 124 * @return 0 or an error code 125 */ 126 GIT_EXTERN(int) git_revwalk_push_glob(git_revwalk *walk, const char *glob); 127 128 /** 129 * Push the repository's HEAD 130 * 131 * @param walk the walker being used for the traversal 132 * @return 0 or an error code 133 */ 134 GIT_EXTERN(int) git_revwalk_push_head(git_revwalk *walk); 135 136 /** 137 * Mark a commit (and its ancestors) uninteresting for the output. 138 * 139 * The given id must belong to a committish on the walked 140 * repository. 141 * 142 * The resolved commit and all its parents will be hidden from the 143 * output on the revision walk. 144 * 145 * @param walk the walker being used for the traversal. 146 * @param commit_id the oid of commit that will be ignored during the traversal 147 * @return 0 or an error code 148 */ 149 GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *commit_id); 150 151 /** 152 * Hide matching references. 153 * 154 * The OIDs pointed to by the references that match the given glob 155 * pattern and their ancestors will be hidden from the output on the 156 * revision walk. 157 * 158 * A leading 'refs/' is implied if not present as well as a trailing 159 * '/\*' if the glob lacks '?', '\*' or '['. 160 * 161 * Any references matching this glob which do not point to a 162 * committish will be ignored. 163 * 164 * @param walk the walker being used for the traversal 165 * @param glob the glob pattern references should match 166 * @return 0 or an error code 167 */ 168 GIT_EXTERN(int) git_revwalk_hide_glob(git_revwalk *walk, const char *glob); 169 170 /** 171 * Hide the repository's HEAD 172 * 173 * @param walk the walker being used for the traversal 174 * @return 0 or an error code 175 */ 176 GIT_EXTERN(int) git_revwalk_hide_head(git_revwalk *walk); 177 178 /** 179 * Push the OID pointed to by a reference 180 * 181 * The reference must point to a committish. 182 * 183 * @param walk the walker being used for the traversal 184 * @param refname the reference to push 185 * @return 0 or an error code 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 * 192 * The reference must point to a committish. 193 * 194 * @param walk the walker being used for the traversal 195 * @param refname the reference to hide 196 * @return 0 or an error code 197 */ 198 GIT_EXTERN(int) git_revwalk_hide_ref(git_revwalk *walk, const char *refname); 199 200 /** 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). 210 * 211 * The revision walker is reset when the walk is over. 212 * 213 * @param out Pointer where to store the oid of the next commit 214 * @param walk the walker to pop the commit from. 215 * @return 0 if the next commit was found; 216 * GIT_ITEROVER if there are no commits left to iterate 217 */ 218 GIT_EXTERN(int) git_revwalk_next(git_oid *out, git_revwalk *walk); 219 220 /** 221 * Change the sorting mode when iterating through the 222 * repository's contents. 223 * 224 * Changing the sorting mode resets the walker. 225 * 226 * @param walk the walker being used for the traversal. 227 * @param sort_mode combination of GIT_SORT_XXX flags 228 * @return 0 or an error code 229 */ 230 GIT_EXTERN(int) git_revwalk_sorting(git_revwalk *walk, unsigned int sort_mode); 231 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 247 /** 248 * Simplify the history by first-parent 249 * 250 * No parents other than the first for each commit will be enqueued. 251 * 252 * @return 0 or an error code 253 */ 254 GIT_EXTERN(int) git_revwalk_simplify_first_parent(git_revwalk *walk); 255 256 257 /** 258 * Free a revision walker previously allocated. 259 * 260 * @param walk traversal handle to close. If NULL nothing occurs. 261 */ 262 GIT_EXTERN(void) git_revwalk_free(git_revwalk *walk); 263 264 /** 265 * Return the repository on which this walker 266 * is operating. 267 * 268 * @param walk the revision walker 269 * @return the repository being walked 270 */ 271 GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk); 272 273 /** 274 * This is a callback function that user can provide to hide a 275 * commit and its parents. If the callback function returns non-zero value, 276 * then this commit and its parents will be hidden. 277 * 278 * @param commit_id oid of Commit 279 * @param payload User-specified pointer to data to be passed as data payload 280 */ 281 typedef int GIT_CALLBACK(git_revwalk_hide_cb)( 282 const git_oid *commit_id, 283 void *payload); 284 285 /** 286 * Adds, changes or removes a callback function to hide a commit and its parents 287 * 288 * @param walk the revision walker 289 * @param hide_cb callback function to hide a commit and its parents 290 * @param payload data payload to be passed to callback function 291 */ 292 GIT_EXTERN(int) git_revwalk_add_hide_cb( 293 git_revwalk *walk, 294 git_revwalk_hide_cb hide_cb, 295 void *payload); 296 297 /** @} */ 298 GIT_END_DECL 299 #endif 300