[thirdparty/git.git] / list-objects-filter.h

#ifndef LIST_OBJECTS_FILTER_H
#define LIST_OBJECTS_FILTER_H

struct list_objects_filter_options;
struct object;
struct oidset;

/*
 * During list-object traversal we allow certain objects to be
 * filtered (omitted) from the result.  The active filter uses
 * these result values to guide list-objects.
 *
 * _ZERO      : Do nothing with the object at this time.  It may
 *              be revisited if it appears in another place in
 *              the tree or in another commit during the overall
 *              traversal.
 *
 * _MARK_SEEN : Mark this object as "SEEN" in the object flags.
 *              This will prevent it from being revisited during
 *              the remainder of the traversal.  This DOES NOT
 *              imply that it will be included in the results.
 *
 * _DO_SHOW   : Show this object in the results (call show() on it).
 *              In general, objects should only be shown once, but
 *              this result DOES NOT imply that we mark it SEEN.
 *
 * _SKIP_TREE : Used in LOFS_BEGIN_TREE situation - indicates that
 *              the tree's children should not be iterated over. This
 *              is used as an optimization when all children will
 *              definitely be ignored.
 *
 * Most of the time, you want the combination (_MARK_SEEN | _DO_SHOW)
 * but they can be used independently, such as when sparse-checkout
 * pattern matching is being applied.
 *
 * A _MARK_SEEN without _DO_SHOW can be called a hard-omit -- the
 * object is not shown and will never be reconsidered (unless a
 * previous iteration has already shown it).
 *
 * A _DO_SHOW without _MARK_SEEN can be used, for example, to
 * include a directory, but then revisit it to selectively include
 * or omit objects within it.
 *
 * A _ZERO can be called a provisional-omit -- the object is NOT shown,
 * but *may* be revisited (if the object appears again in the traversal).
 * Therefore, it will be omitted from the results *unless* a later
 * iteration causes it to be shown.
 */
enum list_objects_filter_result {
	LOFR_ZERO      = 0,
	LOFR_MARK_SEEN = 1<<0,
	LOFR_DO_SHOW   = 1<<1,
	LOFR_SKIP_TREE = 1<<2,
};

enum list_objects_filter_situation {
	LOFS_BEGIN_TREE,
	LOFS_END_TREE,
	LOFS_BLOB
};

typedef enum list_objects_filter_result (*filter_object_fn)(
	enum list_objects_filter_situation filter_situation,
	struct object *obj,
	const char *pathname,
	const char *filename,
	void *filter_data);

typedef void (*filter_free_fn)(void *filter_data);

/*
 * Constructor for the set of defined list-objects filters.
 * Returns a generic "void *filter_data".
 *
 * The returned "filter_fn" will be used by traverse_commit_list()
 * to filter the results.
 *
 * The returned "filter_free_fn" is a destructor for the
 * filter_data.
 */
void *list_objects_filter__init(
	struct oidset *omitted,
	struct list_objects_filter_options *filter_options,
	filter_object_fn *filter_fn,
	filter_free_fn *filter_free_fn);

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