|
Packit Service |
20376f |
/*
|
|
Packit Service |
20376f |
* Copyright (C) the libgit2 contributors. All rights reserved.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* This file is part of libgit2, distributed under the GNU GPL v2 with
|
|
Packit Service |
20376f |
* a Linking Exception. For full terms see the included COPYING file.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
#ifndef INCLUDE_sys_git_filter_h__
|
|
Packit Service |
20376f |
#define INCLUDE_sys_git_filter_h__
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
#include "git2/filter.h"
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* @file git2/sys/filter.h
|
|
Packit Service |
20376f |
* @brief Git filter backend and plugin routines
|
|
Packit Service |
20376f |
* @defgroup git_backend Git custom backend APIs
|
|
Packit Service |
20376f |
* @ingroup Git
|
|
Packit Service |
20376f |
* @{
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_BEGIN_DECL
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Look up a filter by name
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* @param name The name of the filter
|
|
Packit Service |
20376f |
* @return Pointer to the filter object or NULL if not found
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(git_filter *) git_filter_lookup(const char *name);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
#define GIT_FILTER_CRLF "crlf"
|
|
Packit Service |
20376f |
#define GIT_FILTER_IDENT "ident"
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* This is priority that the internal CRLF filter will be registered with
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
#define GIT_FILTER_CRLF_PRIORITY 0
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* This is priority that the internal ident filter will be registered with
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
#define GIT_FILTER_IDENT_PRIORITY 100
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* This is priority to use with a custom filter to imitate a core Git
|
|
Packit Service |
20376f |
* filter driver, so that it will be run last on checkout and first on
|
|
Packit Service |
20376f |
* checkin. You do not have to use this, but it helps compatibility.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
#define GIT_FILTER_DRIVER_PRIORITY 200
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Create a new empty filter list
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Normally you won't use this because `git_filter_list_load` will create
|
|
Packit Service |
20376f |
* the filter list for you, but you can use this in combination with the
|
|
Packit Service |
20376f |
* `git_filter_lookup` and `git_filter_list_push` functions to assemble
|
|
Packit Service |
20376f |
* your own chains of filters.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(int) git_filter_list_new(
|
|
Packit Service |
20376f |
git_filter_list **out,
|
|
Packit Service |
20376f |
git_repository *repo,
|
|
Packit Service |
20376f |
git_filter_mode_t mode,
|
|
Packit Service |
20376f |
uint32_t options);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Add a filter to a filter list with the given payload.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Normally you won't have to do this because the filter list is created
|
|
Packit Service |
20376f |
* by calling the "check" function on registered filters when the filter
|
|
Packit Service |
20376f |
* attributes are set, but this does allow more direct manipulation of
|
|
Packit Service |
20376f |
* filter lists when desired.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Note that normally the "check" function can set up a payload for the
|
|
Packit Service |
20376f |
* filter. Using this function, you can either pass in a payload if you
|
|
Packit Service |
20376f |
* know the expected payload format, or you can pass NULL. Some filters
|
|
Packit Service |
20376f |
* may fail with a NULL payload. Good luck!
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(int) git_filter_list_push(
|
|
Packit Service |
20376f |
git_filter_list *fl, git_filter *filter, void *payload);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Look up how many filters are in the list
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* We will attempt to apply all of these filters to any data passed in,
|
|
Packit Service |
20376f |
* but note that the filter apply action still has the option of skipping
|
|
Packit Service |
20376f |
* data that is passed in (for example, the CRLF filter will skip data
|
|
Packit Service |
20376f |
* that appears to be binary).
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* @param fl A filter list
|
|
Packit Service |
20376f |
* @return The number of filters in the list
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(size_t) git_filter_list_length(const git_filter_list *fl);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* A filter source represents a file/blob to be processed
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
typedef struct git_filter_source git_filter_source;
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Get the repository that the source data is coming from.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(git_repository *) git_filter_source_repo(const git_filter_source *src);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Get the path that the source data is coming from.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(const char *) git_filter_source_path(const git_filter_source *src);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Get the file mode of the source file
|
|
Packit Service |
20376f |
* If the mode is unknown, this will return 0
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(uint16_t) git_filter_source_filemode(const git_filter_source *src);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Get the OID of the source
|
|
Packit Service |
20376f |
* If the OID is unknown (often the case with GIT_FILTER_CLEAN) then
|
|
Packit Service |
20376f |
* this will return NULL.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(const git_oid *) git_filter_source_id(const git_filter_source *src);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Get the git_filter_mode_t to be used
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(git_filter_mode_t) git_filter_source_mode(const git_filter_source *src);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Get the combination git_filter_flag_t options to be applied
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(uint32_t) git_filter_source_flags(const git_filter_source *src);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Initialize callback on filter
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Specified as `filter.initialize`, this is an optional callback invoked
|
|
Packit Service |
20376f |
* before a filter is first used. It will be called once at most.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* If non-NULL, the filter's `initialize` callback will be invoked right
|
|
Packit Service |
20376f |
* before the first use of the filter, so you can defer expensive
|
|
Packit Service |
20376f |
* initialization operations (in case libgit2 is being used in a way that
|
|
Packit Service |
20376f |
* doesn't need the filter).
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
typedef int (*git_filter_init_fn)(git_filter *self);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Shutdown callback on filter
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Specified as `filter.shutdown`, this is an optional callback invoked
|
|
Packit Service |
20376f |
* when the filter is unregistered or when libgit2 is shutting down. It
|
|
Packit Service |
20376f |
* will be called once at most and should release resources as needed.
|
|
Packit Service |
20376f |
* This may be called even if the `initialize` callback was not made.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Typically this function will free the `git_filter` object itself.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
typedef void (*git_filter_shutdown_fn)(git_filter *self);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Callback to decide if a given source needs this filter
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Specified as `filter.check`, this is an optional callback that checks
|
|
Packit Service |
20376f |
* if filtering is needed for a given source.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* It should return 0 if the filter should be applied (i.e. success),
|
|
Packit Service |
20376f |
* GIT_PASSTHROUGH if the filter should not be applied, or an error code
|
|
Packit Service |
20376f |
* to fail out of the filter processing pipeline and return to the caller.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* The `attr_values` will be set to the values of any attributes given in
|
|
Packit Service |
20376f |
* the filter definition. See `git_filter` below for more detail.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* The `payload` will be a pointer to a reference payload for the filter.
|
|
Packit Service |
20376f |
* This will start as NULL, but `check` can assign to this pointer for
|
|
Packit Service |
20376f |
* later use by the `apply` callback. Note that the value should be heap
|
|
Packit Service |
20376f |
* allocated (not stack), so that it doesn't go away before the `apply`
|
|
Packit Service |
20376f |
* callback can use it. If a filter allocates and assigns a value to the
|
|
Packit Service |
20376f |
* `payload`, it will need a `cleanup` callback to free the payload.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
typedef int (*git_filter_check_fn)(
|
|
Packit Service |
20376f |
git_filter *self,
|
|
Packit Service |
20376f |
void **payload, /* points to NULL ptr on entry, may be set */
|
|
Packit Service |
20376f |
const git_filter_source *src,
|
|
Packit Service |
20376f |
const char **attr_values);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Callback to actually perform the data filtering
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Specified as `filter.apply`, this is the callback that actually filters
|
|
Packit Service |
20376f |
* data. If it successfully writes the output, it should return 0. Like
|
|
Packit Service |
20376f |
* `check`, it can return GIT_PASSTHROUGH to indicate that the filter
|
|
Packit Service |
20376f |
* doesn't want to run. Other error codes will stop filter processing and
|
|
Packit Service |
20376f |
* return to the caller.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* The `payload` value will refer to any payload that was set by the
|
|
Packit Service |
20376f |
* `check` callback. It may be read from or written to as needed.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
typedef int (*git_filter_apply_fn)(
|
|
Packit Service |
20376f |
git_filter *self,
|
|
Packit Service |
20376f |
void **payload, /* may be read and/or set */
|
|
Packit Service |
20376f |
git_buf *to,
|
|
Packit Service |
20376f |
const git_buf *from,
|
|
Packit Service |
20376f |
const git_filter_source *src);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
typedef int (*git_filter_stream_fn)(
|
|
Packit Service |
20376f |
git_writestream **out,
|
|
Packit Service |
20376f |
git_filter *self,
|
|
Packit Service |
20376f |
void **payload,
|
|
Packit Service |
20376f |
const git_filter_source *src,
|
|
Packit Service |
20376f |
git_writestream *next);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Callback to clean up after filtering has been applied
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Specified as `filter.cleanup`, this is an optional callback invoked
|
|
Packit Service |
20376f |
* after the filter has been applied. If the `check` or `apply` callbacks
|
|
Packit Service |
20376f |
* allocated a `payload` to keep per-source filter state, use this
|
|
Packit Service |
20376f |
* callback to free that payload and release resources as required.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
typedef void (*git_filter_cleanup_fn)(
|
|
Packit Service |
20376f |
git_filter *self,
|
|
Packit Service |
20376f |
void *payload);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Filter structure used to register custom filters.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* To associate extra data with a filter, allocate extra data and put the
|
|
Packit Service |
20376f |
* `git_filter` struct at the start of your data buffer, then cast the
|
|
Packit Service |
20376f |
* `self` pointer to your larger structure when your callback is invoked.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
struct git_filter {
|
|
Packit Service |
20376f |
/** The `version` field should be set to `GIT_FILTER_VERSION`. */
|
|
Packit Service |
20376f |
unsigned int version;
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* A whitespace-separated list of attribute names to check for this
|
|
Packit Service |
20376f |
* filter (e.g. "eol crlf text"). If the attribute name is bare, it
|
|
Packit Service |
20376f |
* will be simply loaded and passed to the `check` callback. If it
|
|
Packit Service |
20376f |
* has a value (i.e. "name=value"), the attribute must match that
|
|
Packit Service |
20376f |
* value for the filter to be applied. The value may be a wildcard
|
|
Packit Service |
20376f |
* (eg, "name=*"), in which case the filter will be invoked for any
|
|
Packit Service |
20376f |
* value for the given attribute name. See the attribute parameter
|
|
Packit Service |
20376f |
* of the `check` callback for the attribute value that was specified.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
const char *attributes;
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/** Called when the filter is first used for any file. */
|
|
Packit Service |
20376f |
git_filter_init_fn initialize;
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/** Called when the filter is removed or unregistered from the system. */
|
|
Packit Service |
20376f |
git_filter_shutdown_fn shutdown;
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Called to determine whether the filter should be invoked for a
|
|
Packit Service |
20376f |
* given file. If this function returns `GIT_PASSTHROUGH` then the
|
|
Packit Service |
20376f |
* `apply` function will not be invoked and the contents will be passed
|
|
Packit Service |
20376f |
* through unmodified.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
git_filter_check_fn check;
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Called to actually apply the filter to file contents. If this
|
|
Packit Service |
20376f |
* function returns `GIT_PASSTHROUGH` then the contents will be passed
|
|
Packit Service |
20376f |
* through unmodified.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
git_filter_apply_fn apply;
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Called to apply the filter in a streaming manner. If this is not
|
|
Packit Service |
20376f |
* specified then the system will call `apply` with the whole buffer.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
git_filter_stream_fn stream;
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/** Called when the system is done filtering for a file. */
|
|
Packit Service |
20376f |
git_filter_cleanup_fn cleanup;
|
|
Packit Service |
20376f |
};
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
#define GIT_FILTER_VERSION 1
|
|
Packit Service |
20376f |
#define GIT_FILTER_INIT {GIT_FILTER_VERSION}
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Initializes a `git_filter` with default values. Equivalent to
|
|
Packit Service |
20376f |
* creating an instance with GIT_FILTER_INIT.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* @param filter the `git_filter` struct to initialize.
|
|
Packit Service |
20376f |
* @param version Version the struct; pass `GIT_FILTER_VERSION`
|
|
Packit Service |
20376f |
* @return Zero on success; -1 on failure.
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(int) git_filter_init(git_filter *filter, unsigned int version);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Register a filter under a given name with a given priority.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* As mentioned elsewhere, the initialize callback will not be invoked
|
|
Packit Service |
20376f |
* immediately. It is deferred until the filter is used in some way.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* A filter's attribute checks and `check` and `apply` callbacks will be
|
|
Packit Service |
20376f |
* issued in order of `priority` on smudge (to workdir), and in reverse
|
|
Packit Service |
20376f |
* order of `priority` on clean (to odb).
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Two filters are preregistered with libgit2:
|
|
Packit Service |
20376f |
* - GIT_FILTER_CRLF with priority 0
|
|
Packit Service |
20376f |
* - GIT_FILTER_IDENT with priority 100
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Currently the filter registry is not thread safe, so any registering or
|
|
Packit Service |
20376f |
* deregistering of filters must be done outside of any possible usage of
|
|
Packit Service |
20376f |
* the filters (i.e. during application setup or shutdown).
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* @param name A name by which the filter can be referenced. Attempting
|
|
Packit Service |
20376f |
* to register with an in-use name will return GIT_EEXISTS.
|
|
Packit Service |
20376f |
* @param filter The filter definition. This pointer will be stored as is
|
|
Packit Service |
20376f |
* by libgit2 so it must be a durable allocation (either static
|
|
Packit Service |
20376f |
* or on the heap).
|
|
Packit Service |
20376f |
* @param priority The priority for filter application
|
|
Packit Service |
20376f |
* @return 0 on successful registry, error code <0 on failure
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(int) git_filter_register(
|
|
Packit Service |
20376f |
const char *name, git_filter *filter, int priority);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/**
|
|
Packit Service |
20376f |
* Remove the filter with the given name
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Attempting to remove the builtin libgit2 filters is not permitted and
|
|
Packit Service |
20376f |
* will return an error.
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* Currently the filter registry is not thread safe, so any registering or
|
|
Packit Service |
20376f |
* deregistering of filters must be done outside of any possible usage of
|
|
Packit Service |
20376f |
* the filters (i.e. during application setup or shutdown).
|
|
Packit Service |
20376f |
*
|
|
Packit Service |
20376f |
* @param name The name under which the filter was registered
|
|
Packit Service |
20376f |
* @return 0 on success, error code <0 on failure
|
|
Packit Service |
20376f |
*/
|
|
Packit Service |
20376f |
GIT_EXTERN(int) git_filter_unregister(const char *name);
|
|
Packit Service |
20376f |
|
|
Packit Service |
20376f |
/** @} */
|
|
Packit Service |
20376f |
GIT_END_DECL
|
|
Packit Service |
20376f |
#endif
|