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         GIT_FILTER_ALLOW_UNSAFE = (1u << 0),
  44 } git_filter_flag_t;
  45
  46 /**
  47  * A filter that can transform file data
  48  *
  49  * This represents a filter that can be used to transform or even replace
  50  * file data.  Libgit2 includes one built in filter and it is possible to
  51  * write your own (see git2/sys/filter.h for information on that).
  52  *
  53  * The two builtin filters are:
  54  *
  55  * * "crlf" which uses the complex rules with the "text", "eol", and
  56  *   "crlf" file attributes to decide how to convert between LF and CRLF
  57  *   line endings
  58  * * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon
  59  *   checkout and replaced "$Id: <anything>$" with "$Id$" on checkin.
  60  */
  61 typedef struct git_filter git_filter;
  62
  63 /**
  64  * List of filters to be applied
  65  *
  66  * This represents a list of filters to be applied to a file / blob.  You
  67  * can build the list with one call, apply it with another, and dispose it
  68  * with a third.  In typical usage, there are not many occasions where a
  69  * git_filter_list is needed directly since the library will generally
  70  * handle conversions for you, but it can be convenient to be able to
  71  * build and apply the list sometimes.
  72  */
  73 typedef struct git_filter_list git_filter_list;
  74
  75 /**
  76  * Load the filter list for a given path.
  77  *
  78  * This will return 0 (success) but set the output git_filter_list to NULL
  79  * if no filters are requested for the given file.
  80  *
  81  * @param filters Output newly created git_filter_list (or NULL)
  82  * @param repo Repository object that contains `path`
  83  * @param blob The blob to which the filter will be applied (if known)
  84  * @param path Relative path of the file to be filtered
  85  * @param mode Filtering direction (WT->ODB or ODB->WT)
  86  * @param flags Combination of `git_filter_flag_t` flags
  87  * @return 0 on success (which could still return NULL if no filters are
  88  *         needed for the requested file), <0 on error
  89  */
  90 GIT_EXTERN(int) git_filter_list_load(
  91         git_filter_list **filters,
  92         git_repository *repo,
  93         git_blob *blob, /* can be NULL */
  94         const char *path,
  95         git_filter_mode_t mode,
  96         uint32_t flags);
  97
  98 /**
  99  * Query the filter list to see if a given filter (by name) will run.
 100  * The built-in filters "crlf" and "ident" can be queried, otherwise this
 101  * is the name of the filter specified by the filter attribute.
 102  *
 103  * This will return 0 if the given filter is not in the list, or 1 if
 104  * the filter will be applied.
 105  *
 106  * @param filters A loaded git_filter_list (or NULL)
 107  * @param name The name of the filter to query
 108  * @return 1 if the filter is in the list, 0 otherwise
 109  */
 110 GIT_EXTERN(int) git_filter_list_contains(
 111         git_filter_list *filters,
 112         const char *name);
 113
 114 /**
 115  * Apply filter list to a data buffer.
 116  *
 117  * See `git2/buffer.h` for background on `git_buf` objects.
 118  *
 119  * If the `in` buffer holds data allocated by libgit2 (i.e. `in->asize` is
 120  * not zero), then it will be overwritten when applying the filters.  If
 121  * not, then it will be left untouched.
 122  *
 123  * If there are no filters to apply (or `filters` is NULL), then the `out`
 124  * buffer will reference the `in` buffer data (with `asize` set to zero)
 125  * instead of allocating data.  This keeps allocations to a minimum, but
 126  * it means you have to be careful about freeing the `in` data since `out`
 127  * may be pointing to it!
 128  *
 129  * @param out Buffer to store the result of the filtering
 130  * @param filters A loaded git_filter_list (or NULL)
 131  * @param in Buffer containing the data to filter
 132  * @return 0 on success, an error code otherwise
 133  */
 134 GIT_EXTERN(int) git_filter_list_apply_to_data(
 135         git_buf *out,
 136         git_filter_list *filters,
 137         git_buf *in);
 138
 139 /**
 140  * Apply a filter list to the contents of a file on disk
 141  *
 142  * @param out buffer into which to store the filtered file
 143  * @param filters the list of filters to apply
 144  * @param repo the repository in which to perform the filtering
 145  * @param path the path of the file to filter, a relative path will be
 146  * taken as relative to the workdir
 147  */
 148 GIT_EXTERN(int) git_filter_list_apply_to_file(
 149         git_buf *out,
 150         git_filter_list *filters,
 151         git_repository *repo,
 152         const char *path);
 153
 154 /**
 155  * Apply a filter list to the contents of a blob
 156  *
 157  * @param out buffer into which to store the filtered file
 158  * @param filters the list of filters to apply
 159  * @param blob the blob to filter
 160  */
 161 GIT_EXTERN(int) git_filter_list_apply_to_blob(
 162         git_buf *out,
 163         git_filter_list *filters,
 164         git_blob *blob);
 165
 166 /**
 167  * Apply a filter list to an arbitrary buffer as a stream
 168  *
 169  * @param filters the list of filters to apply
 170  * @param data the buffer to filter
 171  * @param target the stream into which the data will be written
 172  */
 173 GIT_EXTERN(int) git_filter_list_stream_data(
 174         git_filter_list *filters,
 175         git_buf *data,
 176         git_writestream *target);
 177
 178 /**
 179  * Apply a filter list to a file as a stream
 180  *
 181  * @param filters the list of filters to apply
 182  * @param repo the repository in which to perform the filtering
 183  * @param path the path of the file to filter, a relative path will be
 184  * taken as relative to the workdir
 185  * @param target the stream into which the data will be written
 186  */
 187 GIT_EXTERN(int) git_filter_list_stream_file(
 188         git_filter_list *filters,
 189         git_repository *repo,
 190         const char *path,
 191         git_writestream *target);
 192
 193 /**
 194  * Apply a filter list to a blob as a stream
 195  *
 196  * @param filters the list of filters to apply
 197  * @param blob the blob to filter
 198  * @param target the stream into which the data will be written
 199  */
 200 GIT_EXTERN(int) git_filter_list_stream_blob(
 201         git_filter_list *filters,
 202         git_blob *blob,
 203         git_writestream *target);
 204
 205 /**
 206  * Free a git_filter_list
 207  *
 208  * @param filters A git_filter_list created by `git_filter_list_load`
 209  */
 210 GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters);
 211
 212
 213 GIT_END_DECL
 214
 215 /** @} */
 216
 217 #endif