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