include/git2/filter.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   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.
   6  */
   7 #ifndef INCLUDE_git_filter_h__
   8 #define INCLUDE_git_filter_h__
   9
  10 #include "common.h"
  11 #include "types.h"
  12 #include "oid.h"
  13 #include "buffer.h"
  14
  15 /**
  16  * @file git2/filter.h
  17  * @brief Git filter APIs
  18  *
  19  * @ingroup Git
  20  * @{
  21  */
  22 GIT_BEGIN_DECL
  23
  24 /**
  25  * Filters are applied in one of two directions: smudging - which is
  26  * exporting a file from the Git object database to the working directory,
  27  * and cleaning - which is importing a file from the working directory to
  28  * the Git object database.  These values control which direction of
  29  * change is being applied.
  30  */
  31 typedef enum {
  32         GIT_FILTER_TO_WORKTREE = 0,
  33         GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE,
  34         GIT_FILTER_TO_ODB = 1,
  35         GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB,
  36 } git_filter_mode_t;
  37
  38 /**
  39  * Filter option flags.
  40  */
  41 typedef enum {
  42         GIT_FILTER_DEFAULT = 0u,
  43
  44         /** Don't error for `safecrlf` violations, allow them to continue. */
  45         GIT_FILTER_ALLOW_UNSAFE = (1u << 0),
  46
  47         /** Don't load `/etc/gitattributes` (or the system equivalent) */
  48         GIT_FILTER_NO_SYSTEM_ATTRIBUTES = (1u << 1),
  49
  50         /** Load attributes from `.gitattributes` in the root of HEAD */
  51         GIT_FILTER_ATTRIBUTES_FROM_HEAD = (1u << 2),
  52
  53         /**
  54          * Load attributes from `.gitattributes` in a given commit.
  55          * This can only be specified in a `git_filter_options`.
  56          */
  57         GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3),
  58 } git_filter_flag_t;
  59
  60 /**
  61  * Filtering options
  62  */
  63 typedef struct {
  64         unsigned int version;
  65
  66         /** See `git_filter_flag_t` above */
  67         uint32_t flags;
  68
  69 #ifdef GIT_DEPRECATE_HARD
  70         void *reserved;
  71 #else
  72         git_oid *commit_id;
  73 #endif
  74
  75         /**
  76          * The commit to load attributes from, when
  77          * `GIT_FILTER_ATTRIBUTES_FROM_COMMIT` is specified.
  78          */
  79         git_oid attr_commit_id;
  80 } git_filter_options;
  81
  82  #define GIT_FILTER_OPTIONS_VERSION 1
  83  #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION}
  84
  85 /**
  86  * A filter that can transform file data
  87  *
  88  * This represents a filter that can be used to transform or even replace
  89  * file data.  Libgit2 includes one built in filter and it is possible to
  90  * write your own (see git2/sys/filter.h for information on that).
  91  *
  92  * The two builtin filters are:
  93  *
  94  * * "crlf" which uses the complex rules with the "text", "eol", and
  95  *   "crlf" file attributes to decide how to convert between LF and CRLF
  96  *   line endings
  97  * * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon
  98  *   checkout and replaced "$Id: <anything>$" with "$Id$" on checkin.
  99  */
 100 typedef struct git_filter git_filter;
 101
 102 /**
 103  * List of filters to be applied
 104  *
 105  * This represents a list of filters to be applied to a file / blob.  You
 106  * can build the list with one call, apply it with another, and dispose it
 107  * with a third.  In typical usage, there are not many occasions where a
 108  * git_filter_list is needed directly since the library will generally
 109  * handle conversions for you, but it can be convenient to be able to
 110  * build and apply the list sometimes.
 111  */
 112 typedef struct git_filter_list git_filter_list;
 113
 114 /**
 115  * Load the filter list for a given path.
 116  *
 117  * This will return 0 (success) but set the output git_filter_list to NULL
 118  * if no filters are requested for the given file.
 119  *
 120  * @param filters Output newly created git_filter_list (or NULL)
 121  * @param repo Repository object that contains `path`
 122  * @param blob The blob to which the filter will be applied (if known)
 123  * @param path Relative path of the file to be filtered
 124  * @param mode Filtering direction (WT->ODB or ODB->WT)
 125  * @param flags Combination of `git_filter_flag_t` flags
 126  * @return 0 on success (which could still return NULL if no filters are
 127  *         needed for the requested file), <0 on error
 128  */
 129 GIT_EXTERN(int) git_filter_list_load(
 130         git_filter_list **filters,
 131         git_repository *repo,
 132         git_blob *blob, /* can be NULL */
 133         const char *path,
 134         git_filter_mode_t mode,
 135         uint32_t flags);
 136
 137 /**
 138  * Load the filter list for a given path.
 139  *
 140  * This will return 0 (success) but set the output git_filter_list to NULL
 141  * if no filters are requested for the given file.
 142  *
 143  * @param filters Output newly created git_filter_list (or NULL)
 144  * @param repo Repository object that contains `path`
 145  * @param blob The blob to which the filter will be applied (if known)
 146  * @param path Relative path of the file to be filtered
 147  * @param mode Filtering direction (WT->ODB or ODB->WT)
 148  * @param opts The `git_filter_options` to use when loading filters
 149  * @return 0 on success (which could still return NULL if no filters are
 150  *         needed for the requested file), <0 on error
 151  */
 152 GIT_EXTERN(int) git_filter_list_load_ext(
 153         git_filter_list **filters,
 154         git_repository *repo,
 155         git_blob *blob,
 156         const char *path,
 157         git_filter_mode_t mode,
 158         git_filter_options *opts);
 159
 160 /**
 161  * Query the filter list to see if a given filter (by name) will run.
 162  * The built-in filters "crlf" and "ident" can be queried, otherwise this
 163  * is the name of the filter specified by the filter attribute.
 164  *
 165  * This will return 0 if the given filter is not in the list, or 1 if
 166  * the filter will be applied.
 167  *
 168  * @param filters A loaded git_filter_list (or NULL)
 169  * @param name The name of the filter to query
 170  * @return 1 if the filter is in the list, 0 otherwise
 171  */
 172 GIT_EXTERN(int) git_filter_list_contains(
 173         git_filter_list *filters,
 174         const char *name);
 175
 176 /**
 177  * Apply filter list to a data buffer.
 178  *
 179  * @param out Buffer to store the result of the filtering
 180  * @param filters A loaded git_filter_list (or NULL)
 181  * @param in Buffer containing the data to filter
 182  * @param in_len The length of the input buffer
 183  * @return 0 on success, an error code otherwise
 184  */
 185 GIT_EXTERN(int) git_filter_list_apply_to_buffer(
 186         git_buf *out,
 187         git_filter_list *filters,
 188         const char *in,
 189         size_t in_len);
 190
 191 /**
 192  * Apply a filter list to the contents of a file on disk
 193  *
 194  * @param out buffer into which to store the filtered file
 195  * @param filters the list of filters to apply
 196  * @param repo the repository in which to perform the filtering
 197  * @param path the path of the file to filter, a relative path will be
 198  * taken as relative to the workdir
 199  */
 200 GIT_EXTERN(int) git_filter_list_apply_to_file(
 201         git_buf *out,
 202         git_filter_list *filters,
 203         git_repository *repo,
 204         const char *path);
 205
 206 /**
 207  * Apply a filter list to the contents of a blob
 208  *
 209  * @param out buffer into which to store the filtered file
 210  * @param filters the list of filters to apply
 211  * @param blob the blob to filter
 212  */
 213 GIT_EXTERN(int) git_filter_list_apply_to_blob(
 214         git_buf *out,
 215         git_filter_list *filters,
 216         git_blob *blob);
 217
 218 /**
 219  * Apply a filter list to an arbitrary buffer as a stream
 220  *
 221  * @param filters the list of filters to apply
 222  * @param buffer the buffer to filter
 223  * @param len the size of the buffer
 224  * @param target the stream into which the data will be written
 225  */
 226 GIT_EXTERN(int) git_filter_list_stream_buffer(
 227         git_filter_list *filters,
 228         const char *buffer,
 229         size_t len,
 230         git_writestream *target);
 231
 232 /**
 233  * Apply a filter list to a file as a stream
 234  *
 235  * @param filters the list of filters to apply
 236  * @param repo the repository in which to perform the filtering
 237  * @param path the path of the file to filter, a relative path will be
 238  * taken as relative to the workdir
 239  * @param target the stream into which the data will be written
 240  */
 241 GIT_EXTERN(int) git_filter_list_stream_file(
 242         git_filter_list *filters,
 243         git_repository *repo,
 244         const char *path,
 245         git_writestream *target);
 246
 247 /**
 248  * Apply a filter list to a blob as a stream
 249  *
 250  * @param filters the list of filters to apply
 251  * @param blob the blob to filter
 252  * @param target the stream into which the data will be written
 253  */
 254 GIT_EXTERN(int) git_filter_list_stream_blob(
 255         git_filter_list *filters,
 256         git_blob *blob,
 257         git_writestream *target);
 258
 259 /**
 260  * Free a git_filter_list
 261  *
 262  * @param filters A git_filter_list created by `git_filter_list_load`
 263  */
 264 GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters);
 265
 266
 267 GIT_END_DECL
 268
 269 /** @} */
 270
 271 #endif