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