2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_sys_git_filter_h__
8 #define INCLUDE_sys_git_filter_h__
10 #include "git2/filter.h"
13 * @file git2/sys/filter.h
14 * @brief Git filter backend and plugin routines
15 * @defgroup git_backend Git custom backend APIs
22 * Look up a filter by name
24 * @param name The name of the filter
25 * @return Pointer to the filter object or NULL if not found
27 GIT_EXTERN(git_filter
*) git_filter_lookup(const char *name
);
29 #define GIT_FILTER_CRLF "crlf"
30 #define GIT_FILTER_IDENT "ident"
33 * This is priority that the internal CRLF filter will be registered with
35 #define GIT_FILTER_CRLF_PRIORITY 0
38 * This is priority that the internal ident filter will be registered with
40 #define GIT_FILTER_IDENT_PRIORITY 100
43 * This is priority to use with a custom filter to imitate a core Git
44 * filter driver, so that it will be run last on checkout and first on
45 * checkin. You do not have to use this, but it helps compatibility.
47 #define GIT_FILTER_DRIVER_PRIORITY 200
50 * Create a new empty filter list
52 * Normally you won't use this because `git_filter_list_load` will create
53 * the filter list for you, but you can use this in combination with the
54 * `git_filter_lookup` and `git_filter_list_push` functions to assemble
55 * your own chains of filters.
57 GIT_EXTERN(int) git_filter_list_new(
58 git_filter_list
**out
,
60 git_filter_mode_t mode
,
64 * Add a filter to a filter list with the given payload.
66 * Normally you won't have to do this because the filter list is created
67 * by calling the "check" function on registered filters when the filter
68 * attributes are set, but this does allow more direct manipulation of
69 * filter lists when desired.
71 * Note that normally the "check" function can set up a payload for the
72 * filter. Using this function, you can either pass in a payload if you
73 * know the expected payload format, or you can pass NULL. Some filters
74 * may fail with a NULL payload. Good luck!
76 GIT_EXTERN(int) git_filter_list_push(
77 git_filter_list
*fl
, git_filter
*filter
, void *payload
);
80 * Look up how many filters are in the list
82 * We will attempt to apply all of these filters to any data passed in,
83 * but note that the filter apply action still has the option of skipping
84 * data that is passed in (for example, the CRLF filter will skip data
85 * that appears to be binary).
87 * @param fl A filter list
88 * @return The number of filters in the list
90 GIT_EXTERN(size_t) git_filter_list_length(const git_filter_list
*fl
);
93 * A filter source represents a file/blob to be processed
95 typedef struct git_filter_source git_filter_source
;
98 * Get the repository that the source data is coming from.
100 GIT_EXTERN(git_repository
*) git_filter_source_repo(const git_filter_source
*src
);
103 * Get the path that the source data is coming from.
105 GIT_EXTERN(const char *) git_filter_source_path(const git_filter_source
*src
);
108 * Get the file mode of the source file
109 * If the mode is unknown, this will return 0
111 GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source
*src
);
114 * Get the OID of the source
115 * If the OID is unknown (often the case with GIT_FILTER_CLEAN) then
116 * this will return NULL.
118 GIT_EXTERN(const git_oid
*) git_filter_source_id(const git_filter_source
*src
);
121 * Get the git_filter_mode_t to be used
123 GIT_EXTERN(git_filter_mode_t
) git_filter_source_mode(const git_filter_source
*src
);
126 * Get the combination git_filter_flag_t options to be applied
128 GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source
*src
);
133 * The filter lifecycle:
134 * - initialize - first use of filter
135 * - shutdown - filter removed/unregistered from system
136 * - check - considering filter for file
137 * - apply - apply filter to file contents
138 * - cleanup - done with file
142 * Initialize callback on filter
144 * Specified as `filter.initialize`, this is an optional callback invoked
145 * before a filter is first used. It will be called once at most.
147 * If non-NULL, the filter's `initialize` callback will be invoked right
148 * before the first use of the filter, so you can defer expensive
149 * initialization operations (in case libgit2 is being used in a way that
150 * doesn't need the filter).
152 typedef int (*git_filter_init_fn
)(git_filter
*self
);
155 * Shutdown callback on filter
157 * Specified as `filter.shutdown`, this is an optional callback invoked
158 * when the filter is unregistered or when libgit2 is shutting down. It
159 * will be called once at most and should release resources as needed.
160 * This may be called even if the `initialize` callback was not made.
162 * Typically this function will free the `git_filter` object itself.
164 typedef void (*git_filter_shutdown_fn
)(git_filter
*self
);
167 * Callback to decide if a given source needs this filter
169 * Specified as `filter.check`, this is an optional callback that checks
170 * if filtering is needed for a given source.
172 * It should return 0 if the filter should be applied (i.e. success),
173 * GIT_PASSTHROUGH if the filter should not be applied, or an error code
174 * to fail out of the filter processing pipeline and return to the caller.
176 * The `attr_values` will be set to the values of any attributes given in
177 * the filter definition. See `git_filter` below for more detail.
179 * The `payload` will be a pointer to a reference payload for the filter.
180 * This will start as NULL, but `check` can assign to this pointer for
181 * later use by the `apply` callback. Note that the value should be heap
182 * allocated (not stack), so that it doesn't go away before the `apply`
183 * callback can use it. If a filter allocates and assigns a value to the
184 * `payload`, it will need a `cleanup` callback to free the payload.
186 typedef int (*git_filter_check_fn
)(
188 void **payload
, /* points to NULL ptr on entry, may be set */
189 const git_filter_source
*src
,
190 const char **attr_values
);
193 * Callback to actually perform the data filtering
195 * Specified as `filter.apply`, this is the callback that actually filters
196 * data. If it successfully writes the output, it should return 0. Like
197 * `check`, it can return GIT_PASSTHROUGH to indicate that the filter
198 * doesn't want to run. Other error codes will stop filter processing and
199 * return to the caller.
201 * The `payload` value will refer to any payload that was set by the
202 * `check` callback. It may be read from or written to as needed.
204 typedef int (*git_filter_apply_fn
)(
206 void **payload
, /* may be read and/or set */
209 const git_filter_source
*src
);
211 typedef int (*git_filter_stream_fn
)(
212 git_writestream
**out
,
215 const git_filter_source
*src
,
216 git_writestream
*next
);
219 * Callback to clean up after filtering has been applied
221 * Specified as `filter.cleanup`, this is an optional callback invoked
222 * after the filter has been applied. If the `check` or `apply` callbacks
223 * allocated a `payload` to keep per-source filter state, use this
224 * callback to free that payload and release resources as required.
226 typedef void (*git_filter_cleanup_fn
)(
231 * Filter structure used to register custom filters.
233 * To associate extra data with a filter, allocate extra data and put the
234 * `git_filter` struct at the start of your data buffer, then cast the
235 * `self` pointer to your larger structure when your callback is invoked.
237 * `version` should be set to GIT_FILTER_VERSION
239 * `attributes` is a whitespace-separated list of attribute names to check
240 * for this filter (e.g. "eol crlf text"). If the attribute name is bare,
241 * it will be simply loaded and passed to the `check` callback. If it has
242 * a value (i.e. "name=value"), the attribute must match that value for
243 * the filter to be applied.
245 * The `initialize`, `shutdown`, `check`, `apply`, and `cleanup` callbacks
246 * are all documented above with the respective function pointer typedefs.
249 unsigned int version
;
251 const char *attributes
;
253 git_filter_init_fn initialize
;
254 git_filter_shutdown_fn shutdown
;
255 git_filter_check_fn check
;
256 git_filter_apply_fn apply
;
257 git_filter_stream_fn stream
;
258 git_filter_cleanup_fn cleanup
;
261 #define GIT_FILTER_VERSION 1
264 * Register a filter under a given name with a given priority.
266 * As mentioned elsewhere, the initialize callback will not be invoked
267 * immediately. It is deferred until the filter is used in some way.
269 * A filter's attribute checks and `check` and `apply` callbacks will be
270 * issued in order of `priority` on smudge (to workdir), and in reverse
271 * order of `priority` on clean (to odb).
273 * Two filters are preregistered with libgit2:
274 * - GIT_FILTER_CRLF with priority 0
275 * - GIT_FILTER_IDENT with priority 100
277 * Currently the filter registry is not thread safe, so any registering or
278 * deregistering of filters must be done outside of any possible usage of
279 * the filters (i.e. during application setup or shutdown).
281 * @param name A name by which the filter can be referenced. Attempting
282 * to register with an in-use name will return GIT_EEXISTS.
283 * @param filter The filter definition. This pointer will be stored as is
284 * by libgit2 so it must be a durable allocation (either static
286 * @param priority The priority for filter application
287 * @return 0 on successful registry, error code <0 on failure
289 GIT_EXTERN(int) git_filter_register(
290 const char *name
, git_filter
*filter
, int priority
);
293 * Remove the filter with the given name
295 * Attempting to remove the builtin libgit2 filters is not permitted and
296 * will return an error.
298 * Currently the filter registry is not thread safe, so any registering or
299 * deregistering of filters must be done outside of any possible usage of
300 * the filters (i.e. during application setup or shutdown).
302 * @param name The name under which the filter was registered
303 * @return 0 on success, error code <0 on failure
305 GIT_EXTERN(int) git_filter_unregister(const char *name
);