include/git2/filter.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_filter_h__
0008 #define INCLUDE_git_filter_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "oid.h"
0013 #include "buffer.h"
0014
0015 /**
0016  * @file git2/filter.h
0017  * @brief Git filter APIs
0018  *
0019  * @ingroup Git
0020  * @{
0021  */
0022 GIT_BEGIN_DECL
0023
0024 /**
0025  * Filters are applied in one of two directions: smudging - which is
0026  * exporting a file from the Git object database to the working directory,
0027  * and cleaning - which is importing a file from the working directory to
0028  * the Git object database.  These values control which direction of
0029  * change is being applied.
0030  */
0031 typedef enum {
0032     GIT_FILTER_TO_WORKTREE = 0,
0033     GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE,
0034     GIT_FILTER_TO_ODB = 1,
0035     GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB
0036 } git_filter_mode_t;
0037
0038 /**
0039  * Filter option flags.
0040  */
0041 typedef enum {
0042     GIT_FILTER_DEFAULT = 0u,
0043
0044     /** Don't error for `safecrlf` violations, allow them to continue. */
0045     GIT_FILTER_ALLOW_UNSAFE = (1u << 0),
0046
0047     /** Don't load `/etc/gitattributes` (or the system equivalent) */
0048     GIT_FILTER_NO_SYSTEM_ATTRIBUTES = (1u << 1),
0049
0050     /** Load attributes from `.gitattributes` in the root of HEAD */
0051     GIT_FILTER_ATTRIBUTES_FROM_HEAD = (1u << 2),
0052
0053     /**
0054      * Load attributes from `.gitattributes` in a given commit.
0055      * This can only be specified in a `git_filter_options`.
0056      */
0057     GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3)
0058 } git_filter_flag_t;
0059
0060 /**
0061  * Filtering options
0062  */
0063 typedef struct {
0064     unsigned int version;
0065
0066     /** See `git_filter_flag_t` above */
0067     uint32_t flags;
0068
0069 #ifdef GIT_DEPRECATE_HARD
0070     void *reserved;
0071 #else
0072     git_oid *commit_id;
0073 #endif
0074
0075     /**
0076      * The commit to load attributes from, when
0077      * `GIT_FILTER_ATTRIBUTES_FROM_COMMIT` is specified.
0078      */
0079     git_oid attr_commit_id;
0080 } git_filter_options;
0081
0082  #define GIT_FILTER_OPTIONS_VERSION 1
0083  #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION}
0084
0085 /**
0086  * A filter that can transform file data
0087  *
0088  * This represents a filter that can be used to transform or even replace
0089  * file data.  Libgit2 includes one built in filter and it is possible to
0090  * write your own (see git2/sys/filter.h for information on that).
0091  *
0092  * The two builtin filters are:
0093  *
0094  * * "crlf" which uses the complex rules with the "text", "eol", and
0095  *   "crlf" file attributes to decide how to convert between LF and CRLF
0096  *   line endings
0097  * * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon
0098  *   checkout and replaced "$Id: <anything>$" with "$Id$" on checkin.
0099  */
0100 typedef struct git_filter git_filter;
0101
0102 /**
0103  * List of filters to be applied
0104  *
0105  * This represents a list of filters to be applied to a file / blob.  You
0106  * can build the list with one call, apply it with another, and dispose it
0107  * with a third.  In typical usage, there are not many occasions where a
0108  * git_filter_list is needed directly since the library will generally
0109  * handle conversions for you, but it can be convenient to be able to
0110  * build and apply the list sometimes.
0111  */
0112 typedef struct git_filter_list git_filter_list;
0113
0114 /**
0115  * Load the filter list for a given path.
0116  *
0117  * This will return 0 (success) but set the output git_filter_list to NULL
0118  * if no filters are requested for the given file.
0119  *
0120  * @param filters Output newly created git_filter_list (or NULL)
0121  * @param repo Repository object that contains `path`
0122  * @param blob The blob to which the filter will be applied (if known)
0123  * @param path Relative path of the file to be filtered
0124  * @param mode Filtering direction (WT->ODB or ODB->WT)
0125  * @param flags Combination of `git_filter_flag_t` flags
0126  * @return 0 on success (which could still return NULL if no filters are
0127  *         needed for the requested file), <0 on error
0128  */
0129 GIT_EXTERN(int) git_filter_list_load(
0130     git_filter_list **filters,
0131     git_repository *repo,
0132     git_blob *blob, /* can be NULL */
0133     const char *path,
0134     git_filter_mode_t mode,
0135     uint32_t flags);
0136
0137 /**
0138  * Load the filter list for a given path.
0139  *
0140  * This will return 0 (success) but set the output git_filter_list to NULL
0141  * if no filters are requested for the given file.
0142  *
0143  * @param filters Output newly created git_filter_list (or NULL)
0144  * @param repo Repository object that contains `path`
0145  * @param blob The blob to which the filter will be applied (if known)
0146  * @param path Relative path of the file to be filtered
0147  * @param mode Filtering direction (WT->ODB or ODB->WT)
0148  * @param opts The `git_filter_options` to use when loading filters
0149  * @return 0 on success (which could still return NULL if no filters are
0150  *         needed for the requested file), <0 on error
0151  */
0152 GIT_EXTERN(int) git_filter_list_load_ext(
0153     git_filter_list **filters,
0154     git_repository *repo,
0155     git_blob *blob,
0156     const char *path,
0157     git_filter_mode_t mode,
0158     git_filter_options *opts);
0159
0160 /**
0161  * Query the filter list to see if a given filter (by name) will run.
0162  * The built-in filters "crlf" and "ident" can be queried, otherwise this
0163  * is the name of the filter specified by the filter attribute.
0164  *
0165  * This will return 0 if the given filter is not in the list, or 1 if
0166  * the filter will be applied.
0167  *
0168  * @param filters A loaded git_filter_list (or NULL)
0169  * @param name The name of the filter to query
0170  * @return 1 if the filter is in the list, 0 otherwise
0171  */
0172 GIT_EXTERN(int) git_filter_list_contains(
0173     git_filter_list *filters,
0174     const char *name);
0175
0176 /**
0177  * Apply filter list to a data buffer.
0178  *
0179  * @param out Buffer to store the result of the filtering
0180  * @param filters A loaded git_filter_list (or NULL)
0181  * @param in Buffer containing the data to filter
0182  * @param in_len The length of the input buffer
0183  * @return 0 on success, an error code otherwise
0184  */
0185 GIT_EXTERN(int) git_filter_list_apply_to_buffer(
0186     git_buf *out,
0187     git_filter_list *filters,
0188     const char *in,
0189     size_t in_len);
0190
0191 /**
0192  * Apply a filter list to the contents of a file on disk
0193  *
0194  * @param out buffer into which to store the filtered file
0195  * @param filters the list of filters to apply
0196  * @param repo the repository in which to perform the filtering
0197  * @param path the path of the file to filter, a relative path will be
0198  * taken as relative to the workdir
0199  * @return 0 or an error code.
0200  */
0201 GIT_EXTERN(int) git_filter_list_apply_to_file(
0202     git_buf *out,
0203     git_filter_list *filters,
0204     git_repository *repo,
0205     const char *path);
0206
0207 /**
0208  * Apply a filter list to the contents of a blob
0209  *
0210  * @param out buffer into which to store the filtered file
0211  * @param filters the list of filters to apply
0212  * @param blob the blob to filter
0213  * @return 0 or an error code.
0214  */
0215 GIT_EXTERN(int) git_filter_list_apply_to_blob(
0216     git_buf *out,
0217     git_filter_list *filters,
0218     git_blob *blob);
0219
0220 /**
0221  * Apply a filter list to an arbitrary buffer as a stream
0222  *
0223  * @param filters the list of filters to apply
0224  * @param buffer the buffer to filter
0225  * @param len the size of the buffer
0226  * @param target the stream into which the data will be written
0227  * @return 0 or an error code.
0228  */
0229 GIT_EXTERN(int) git_filter_list_stream_buffer(
0230     git_filter_list *filters,
0231     const char *buffer,
0232     size_t len,
0233     git_writestream *target);
0234
0235 /**
0236  * Apply a filter list to a file as a stream
0237  *
0238  * @param filters the list of filters to apply
0239  * @param repo the repository in which to perform the filtering
0240  * @param path the path of the file to filter, a relative path will be
0241  * taken as relative to the workdir
0242  * @param target the stream into which the data will be written
0243  * @return 0 or an error code.
0244  */
0245 GIT_EXTERN(int) git_filter_list_stream_file(
0246     git_filter_list *filters,
0247     git_repository *repo,
0248     const char *path,
0249     git_writestream *target);
0250
0251 /**
0252  * Apply a filter list to a blob as a stream
0253  *
0254  * @param filters the list of filters to apply
0255  * @param blob the blob to filter
0256  * @param target the stream into which the data will be written
0257  * @return 0 or an error code.
0258  */
0259 GIT_EXTERN(int) git_filter_list_stream_blob(
0260     git_filter_list *filters,
0261     git_blob *blob,
0262     git_writestream *target);
0263
0264 /**
0265  * Free a git_filter_list
0266  *
0267  * @param filters A git_filter_list created by `git_filter_list_load`
0268  */
0269 GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters);
0270
0271
0272 GIT_END_DECL
0273
0274 /** @} */
0275
0276 #endif