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 typedef enum {
  39         GIT_FILTER_OPT_DEFAULT = 0u,
  40         GIT_FILTER_OPT_ALLOW_UNSAFE = (1u << 0),
  41 } git_filter_opt_t;
  42
  43 /**
  44  * A filter that can transform file data
  45  *
  46  * This represents a filter that can be used to transform or even replace
  47  * file data.  Libgit2 includes one built in filter and it is possible to
  48  * write your own (see git2/sys/filter.h for information on that).
  49  *
  50  * The two builtin filters are:
  51  *
  52  * * "crlf" which uses the complex rules with the "text", "eol", and
  53  *   "crlf" file attributes to decide how to convert between LF and CRLF
  54  *   line endings
  55  * * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon
  56  *   checkout and replaced "$Id: <anything>$" with "$Id$" on checkin.
  57  */
  58 typedef struct git_filter git_filter;
  59
  60 /**
  61  * List of filters to be applied
  62  *
  63  * This represents a list of filters to be applied to a file / blob.  You
  64  * can build the list with one call, apply it with another, and dispose it
  65  * with a third.  In typical usage, there are not many occasions where a
  66  * git_filter_list is needed directly since the library will generally
  67  * handle conversions for you, but it can be convenient to be able to
  68  * build and apply the list sometimes.
  69  */
  70 typedef struct git_filter_list git_filter_list;
  71
  72 /**
  73  * Load the filter list for a given path.
  74  *
  75  * This will return 0 (success) but set the output git_filter_list to NULL
  76  * if no filters are requested for the given file.
  77  *
  78  * @param filters Output newly created git_filter_list (or NULL)
  79  * @param repo Repository object that contains `path`
  80  * @param blob The blob to which the filter will be applied (if known)
  81  * @param path Relative path of the file to be filtered
  82  * @param mode Filtering direction (WT->ODB or ODB->WT)
  83  * @param options Combination of `git_filter_opt_t` flags
  84  * @return 0 on success (which could still return NULL if no filters are
  85  *         needed for the requested file), <0 on error
  86  */
  87 GIT_EXTERN(int) git_filter_list_load(
  88         git_filter_list **filters,
  89         git_repository *repo,
  90         git_blob *blob, /* can be NULL */
  91         const char *path,
  92         git_filter_mode_t mode,
  93         uint32_t options);
  94
  95 /**
  96  * Apply filter list to a data buffer.
  97  *
  98  * See `git2/buffer.h` for background on `git_buf` objects.
  99  *
 100  * If the `in` buffer holds data allocated by libgit2 (i.e. `in->asize` is
 101  * not zero), then it will be overwritten when applying the filters.  If
 102  * not, then it will be left untouched.
 103  *
 104  * If there are no filters to apply (or `filters` is NULL), then the `out`
 105  * buffer will reference the `in` buffer data (with `asize` set to zero)
 106  * instead of allocating data.  This keeps allocations to a minimum, but
 107  * it means you have to be careful about freeing the `in` data since `out`
 108  * may be pointing to it!
 109  *
 110  * @param out Buffer to store the result of the filtering
 111  * @param filters A loaded git_filter_list (or NULL)
 112  * @param in Buffer containing the data to filter
 113  * @return 0 on success, an error code otherwise
 114  */
 115 GIT_EXTERN(int) git_filter_list_apply_to_data(
 116         git_buf *out,
 117         git_filter_list *filters,
 118         git_buf *in);
 119
 120 /**
 121  * Apply filter list to the contents of a file on disk
 122  */
 123 GIT_EXTERN(int) git_filter_list_apply_to_file(
 124         git_buf *out,
 125         git_filter_list *filters,
 126         git_repository *repo,
 127         const char *path);
 128
 129 /**
 130  * Apply filter list to the contents of a blob
 131  */
 132 GIT_EXTERN(int) git_filter_list_apply_to_blob(
 133         git_buf *out,
 134         git_filter_list *filters,
 135         git_blob *blob);
 136
 137 /**
 138  * Free a git_filter_list
 139  *
 140  * @param filters A git_filter_list created by `git_filter_list_load`
 141  */
 142 GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters);
 143
 144
 145 GIT_END_DECL
 146
 147 /** @} */
 148
 149 #endif