Andrew's git - gitweb.git/blob - list-objects-filter.h

   1#ifndef LIST_OBJECTS_FILTER_H
   2#define LIST_OBJECTS_FILTER_H
   3
   4struct list_objects_filter_options;
   5struct object;
   6struct oidset;
   7struct 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 */
  50enum 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
  57enum list_objects_filter_situation {
  58        LOFS_BEGIN_TREE,
  59        LOFS_END_TREE,
  60        LOFS_BLOB
  61};
  62
  63struct filter;
  64
  65/*
  66 * Constructor for the set of defined list-objects filters.
  67 * The `omitted` set is optional. It is populated with objects that the
  68 * filter excludes. This set should not be considered finalized until
  69 * after list_objects_filter__free is called on the returned `struct
  70 * filter *`.
  71 */
  72struct filter *list_objects_filter__init(
  73        struct oidset *omitted,
  74        struct list_objects_filter_options *filter_options);
  75
  76/*
  77 * Lets `filter` decide how to handle the `obj`. If `filter` is NULL, this
  78 * function behaves as expected if no filter is configured: all objects are
  79 * included.
  80 */
  81enum list_objects_filter_result list_objects_filter__filter_object(
  82        struct repository *r,
  83        enum list_objects_filter_situation filter_situation,
  84        struct object *obj,
  85        const char *pathname,
  86        const char *filename,
  87        struct filter *filter);
  88
  89/*
  90 * Destroys `filter` and finalizes the `omitted` set, if present. Does
  91 * nothing if `filter` is null.
  92 */
  93void list_objects_filter__free(struct filter *filter);
  94
  95#endif /* LIST_OBJECTS_FILTER_H */