list-objects-filter.h

   1 #ifndef LIST_OBJECTS_FILTER_H
   2 #define LIST_OBJECTS_FILTER_H
   3
   4 struct list_objects_filter_options;
   5 struct object;
   6 struct oidset;
   7 struct repository;
   8
   9 /*
  10  * During list-object traversal we allow certain objects to be
  11  * filtered (omitted) from the result.  The active filter uses
  12  * these result values to guide list-objects.
  13  *
  14  * _ZERO      : Do nothing with the object at this time.  It may
  15  *              be revisited if it appears in another place in
  16  *              the tree or in another commit during the overall
  17  *              traversal.
  18  *
  19  * _MARK_SEEN : Mark this object as "SEEN" in the object flags.
  20  *              This will prevent it from being revisited during
  21  *              the remainder of the traversal.  This DOES NOT
  22  *              imply that it will be included in the results.
  23  *
  24  * _DO_SHOW   : Show this object in the results (call show() on it).
  25  *              In general, objects should only be shown once, but
  26  *              this result DOES NOT imply that we mark it SEEN.
  27  *
  28  * _SKIP_TREE : Used in LOFS_BEGIN_TREE situation - indicates that
  29  *              the tree's children should not be iterated over. This
  30  *              is used as an optimization when all children will
  31  *              definitely be ignored.
  32  *
  33  * Most of the time, you want the combination (_MARK_SEEN | _DO_SHOW)
  34  * but they can be used independently, such as when sparse-checkout
  35  * pattern matching is being applied.
  36  *
  37  * A _MARK_SEEN without _DO_SHOW can be called a hard-omit -- the
  38  * object is not shown and will never be reconsidered (unless a
  39  * previous iteration has already shown it).
  40  *
  41  * A _DO_SHOW without _MARK_SEEN can be used, for example, to
  42  * include a directory, but then revisit it to selectively include
  43  * or omit objects within it.
  44  *
  45  * A _ZERO can be called a provisional-omit -- the object is NOT shown,
  46  * but *may* be revisited (if the object appears again in the traversal).
  47  * Therefore, it will be omitted from the results *unless* a later
  48  * iteration causes it to be shown.
  49  */
  50 enum list_objects_filter_result {
  51         LOFR_ZERO      = 0,
  52         LOFR_MARK_SEEN = 1<<0,
  53         LOFR_DO_SHOW   = 1<<1,
  54         LOFR_SKIP_TREE = 1<<2,
  55 };
  56
  57 enum list_objects_filter_situation {
  58         LOFS_COMMIT,
  59         LOFS_TAG,
  60         LOFS_BEGIN_TREE,
  61         LOFS_END_TREE,
  62         LOFS_BLOB
  63 };
  64
  65 struct filter;
  66
  67 /*
  68  * Constructor for the set of defined list-objects filters.
  69  * The `omitted` set is optional. It is populated with objects that the
  70  * filter excludes. This set should not be considered finalized until
  71  * after list_objects_filter__free is called on the returned `struct
  72  * filter *`.
  73  */
  74 struct filter *list_objects_filter__init(
  75         struct oidset *omitted,
  76         struct list_objects_filter_options *filter_options);
  77
  78 /*
  79  * Lets `filter` decide how to handle the `obj`. If `filter` is NULL, this
  80  * function behaves as expected if no filter is configured: all objects are
  81  * included.
  82  */
  83 enum list_objects_filter_result list_objects_filter__filter_object(
  84         struct repository *r,
  85         enum list_objects_filter_situation filter_situation,
  86         struct object *obj,
  87         const char *pathname,
  88         const char *filename,
  89         struct filter *filter);
  90
  91 /*
  92  * Destroys `filter` and finalizes the `omitted` set, if present. Does
  93  * nothing if `filter` is null.
  94  */
  95 void list_objects_filter__free(struct filter *filter);
  96
  97 #endif /* LIST_OBJECTS_FILTER_H */