blob: 9e98814111cee433ae4b3a31937ce076a5d902ca [file] [log] [blame]
Jeff Hostetler25ec7bc2017-11-21 20:58:50 +00001#ifndef LIST_OBJECTS_FILTER_H
2#define LIST_OBJECTS_FILTER_H
3
Elijah Newrenef3ca952018-08-15 10:54:05 -07004struct list_objects_filter_options;
5struct object;
6struct oidset;
Nguyễn Thái Ngọc Duy01d40c82018-11-10 06:48:51 +01007struct repository;
Elijah Newrenef3ca952018-08-15 10:54:05 -07008
Jeff Hostetler25ec7bc2017-11-21 20:58:50 +00009/*
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 *
Matthew DeVore8b10a202018-10-17 17:39:15 -070028 * _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 *
Jeff Hostetler25ec7bc2017-11-21 20:58:50 +000033 * 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,
Matthew DeVore8b10a202018-10-17 17:39:15 -070054 LOFR_SKIP_TREE = 1<<2,
Jeff Hostetler25ec7bc2017-11-21 20:58:50 +000055};
56
57enum list_objects_filter_situation {
Patrick Steinhardt9a2a4f92021-04-12 15:37:35 +020058 LOFS_COMMIT,
59 LOFS_TAG,
Jeff Hostetler25ec7bc2017-11-21 20:58:50 +000060 LOFS_BEGIN_TREE,
61 LOFS_END_TREE,
62 LOFS_BLOB
63};
64
Matthew DeVore94301472019-06-27 15:54:05 -070065struct filter;
66
Matthew DeVoree987df52019-06-27 15:54:08 -070067/*
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 */
Matthew DeVore94301472019-06-27 15:54:05 -070074struct 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 */
83enum list_objects_filter_result list_objects_filter__filter_object(
Nguyễn Thái Ngọc Duy01d40c82018-11-10 06:48:51 +010084 struct repository *r,
Jeff Hostetler25ec7bc2017-11-21 20:58:50 +000085 enum list_objects_filter_situation filter_situation,
86 struct object *obj,
87 const char *pathname,
88 const char *filename,
Matthew DeVore94301472019-06-27 15:54:05 -070089 struct filter *filter);
Jeff Hostetler25ec7bc2017-11-21 20:58:50 +000090
Matthew DeVoree987df52019-06-27 15:54:08 -070091/*
92 * Destroys `filter` and finalizes the `omitted` set, if present. Does
93 * nothing if `filter` is null.
94 */
Matthew DeVore94301472019-06-27 15:54:05 -070095void list_objects_filter__free(struct filter *filter);
Jeff Hostetler25ec7bc2017-11-21 20:58:50 +000096
97#endif /* LIST_OBJECTS_FILTER_H */