include/git2/revwalk.h

   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 time-order method from git.
  29          * This is the default sorting for new walkers.
  30          */
  31         GIT_SORT_NONE = 0,
  32
  33         /**
  34          * Sort the repository contents in topological order (parents before
  35          * children); this sorting mode can be combined with time sorting to
  36          * produce git's "time-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  */
  88 GIT_EXTERN(void) git_revwalk_reset(git_revwalk *walker);
  89
  90 /**
  91  * Add a new root for the traversal
  92  *
  93  * The pushed commit will be marked as one of the roots from which to
  94  * start the walk. This commit may not be walked if it or a child is
  95  * hidden.
  96  *
  97  * At least one commit must be pushed onto the walker before a walk
  98  * can be started.
  99  *
 100  * The given id must belong to a committish on the walked
 101  * repository.
 102  *
 103  * @param walk the walker being used for the traversal.
 104  * @param id the oid of the commit to start from.
 105  * @return 0 or an error code
 106  */
 107 GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *id);
 108
 109 /**
 110  * Push matching references
 111  *
 112  * The OIDs pointed to by the references that match the given glob
 113  * pattern will be pushed to the revision walker.
 114  *
 115  * A leading 'refs/' is implied if not present as well as a trailing
 116  * '/\*' if the glob lacks '?', '\*' or '['.
 117  *
 118  * Any references matching this glob which do not point to a
 119  * committish will be ignored.
 120  *
 121  * @param walk the walker being used for the traversal
 122  * @param glob the glob pattern references should match
 123  * @return 0 or an error code
 124  */
 125 GIT_EXTERN(int) git_revwalk_push_glob(git_revwalk *walk, const char *glob);
 126
 127 /**
 128  * Push the repository's HEAD
 129  *
 130  * @param walk the walker being used for the traversal
 131  * @return 0 or an error code
 132  */
 133 GIT_EXTERN(int) git_revwalk_push_head(git_revwalk *walk);
 134
 135 /**
 136  * Mark a commit (and its ancestors) uninteresting for the output.
 137  *
 138  * The given id must belong to a committish on the walked
 139  * repository.
 140  *
 141  * The resolved commit and all its parents will be hidden from the
 142  * output on the revision walk.
 143  *
 144  * @param walk the walker being used for the traversal.
 145  * @param commit_id the oid of commit that will be ignored during the traversal
 146  * @return 0 or an error code
 147  */
 148 GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *commit_id);
 149
 150 /**
 151  * Hide matching references.
 152  *
 153  * The OIDs pointed to by the references that match the given glob
 154  * pattern and their ancestors will be hidden from the output on the
 155  * revision walk.
 156  *
 157  * A leading 'refs/' is implied if not present as well as a trailing
 158  * '/\*' if the glob lacks '?', '\*' or '['.
 159  *
 160  * Any references matching this glob which do not point to a
 161  * committish will be ignored.
 162  *
 163  * @param walk the walker being used for the traversal
 164  * @param glob the glob pattern references should match
 165  * @return 0 or an error code
 166  */
 167 GIT_EXTERN(int) git_revwalk_hide_glob(git_revwalk *walk, const char *glob);
 168
 169 /**
 170  * Hide the repository's HEAD
 171  *
 172  * @param walk the walker being used for the traversal
 173  * @return 0 or an error code
 174  */
 175 GIT_EXTERN(int) git_revwalk_hide_head(git_revwalk *walk);
 176
 177 /**
 178  * Push the OID pointed to by a reference
 179  *
 180  * The reference must point to a committish.
 181  *
 182  * @param walk the walker being used for the traversal
 183  * @param refname the reference to push
 184  * @return 0 or an error code
 185  */
 186 GIT_EXTERN(int) git_revwalk_push_ref(git_revwalk *walk, const char *refname);
 187
 188 /**
 189  * Hide 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 hide
 195  * @return 0 or an error code
 196  */
 197 GIT_EXTERN(int) git_revwalk_hide_ref(git_revwalk *walk, const char *refname);
 198
 199 /**
 200  * Get the next commit from the revision walk.
 201  *
 202  * The initial call to this method is *not* blocking when
 203  * iterating through a repo with a time-sorting mode.
 204  *
 205  * Iterating with Topological or inverted modes makes the initial
 206  * call blocking to preprocess the commit list, but this block should be
 207  * mostly unnoticeable on most repositories (topological preprocessing
 208  * times at 0.3s on the git.git repo).
 209  *
 210  * The revision walker is reset when the walk is over.
 211  *
 212  * @param out Pointer where to store the oid of the next commit
 213  * @param walk the walker to pop the commit from.
 214  * @return 0 if the next commit was found;
 215  *      GIT_ITEROVER if there are no commits left to iterate
 216  */
 217 GIT_EXTERN(int) git_revwalk_next(git_oid *out, git_revwalk *walk);
 218
 219 /**
 220  * Change the sorting mode when iterating through the
 221  * repository's contents.
 222  *
 223  * Changing the sorting mode resets the walker.
 224  *
 225  * @param walk the walker being used for the traversal.
 226  * @param sort_mode combination of GIT_SORT_XXX flags
 227  */
 228 GIT_EXTERN(void) git_revwalk_sorting(git_revwalk *walk, unsigned int sort_mode);
 229
 230 /**
 231  * Push and hide the respective endpoints of the given range.
 232  *
 233  * The range should be of the form
 234  *   <commit>..<commit>
 235  * where each <commit> is in the form accepted by 'git_revparse_single'.
 236  * The left-hand commit will be hidden and the right-hand commit pushed.
 237  *
 238  * @param walk the walker being used for the traversal
 239  * @param range the range
 240  * @return 0 or an error code
 241  *
 242  */
 243 GIT_EXTERN(int) git_revwalk_push_range(git_revwalk *walk, const char *range);
 244
 245 /**
 246  * Simplify the history by first-parent
 247  *
 248  * No parents other than the first for each commit will be enqueued.
 249  */
 250 GIT_EXTERN(void) git_revwalk_simplify_first_parent(git_revwalk *walk);
 251
 252
 253 /**
 254  * Free a revision walker previously allocated.
 255  *
 256  * @param walk traversal handle to close. If NULL nothing occurs.
 257  */
 258 GIT_EXTERN(void) git_revwalk_free(git_revwalk *walk);
 259
 260 /**
 261  * Return the repository on which this walker
 262  * is operating.
 263  *
 264  * @param walk the revision walker
 265  * @return the repository being walked
 266  */
 267 GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk);
 268
 269 /**
 270  * This is a callback function that user can provide to hide a
 271  * commit and its parents. If the callback function returns non-zero value,
 272  * then this commit and its parents will be hidden.
 273  *
 274  * @param commit_id oid of Commit
 275  * @param payload User-specified pointer to data to be passed as data payload
 276  */
 277 typedef int(*git_revwalk_hide_cb)(
 278         const git_oid *commit_id,
 279         void *payload);
 280
 281 /**
 282  * Adds a callback function to hide a commit and its parents
 283  *
 284  * @param walk the revision walker
 285  * @param hide_cb  callback function to hide a commit and its parents
 286  * @param payload  data payload to be passed to callback function
 287  */
 288 GIT_EXTERN(int) git_revwalk_add_hide_cb(
 289         git_revwalk *walk,
 290         git_revwalk_hide_cb hide_cb,
 291         void *payload);
 292
 293 /** @} */
 294 GIT_END_DECL
 295 #endif