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 * @param out Buffer to store the result of the filtering 126 * @param filters A loaded git_filter_list (or NULL) 127 * @param in Buffer containing the data to filter 128 * @param in_len The length of the input buffer 129 * @return 0 on success, an error code otherwise 130 */ 131 GIT_EXTERN(int) git_filter_list_apply_to_buffer( 132 git_buf *out, 133 git_filter_list *filters, 134 const char *in, 135 size_t in_len); 136 137 /** 138 * Apply a filter list to the contents of a file on disk 139 * 140 * @param out buffer into which to store the filtered file 141 * @param filters the list of filters to apply 142 * @param repo the repository in which to perform the filtering 143 * @param path the path of the file to filter, a relative path will be 144 * taken as relative to the workdir 145 */ 146 GIT_EXTERN(int) git_filter_list_apply_to_file( 147 git_buf *out, 148 git_filter_list *filters, 149 git_repository *repo, 150 const char *path); 151 152 /** 153 * Apply a filter list to the contents of a blob 154 * 155 * @param out buffer into which to store the filtered file 156 * @param filters the list of filters to apply 157 * @param blob the blob to filter 158 */ 159 GIT_EXTERN(int) git_filter_list_apply_to_blob( 160 git_buf *out, 161 git_filter_list *filters, 162 git_blob *blob); 163 164 /** 165 * Apply a filter list to an arbitrary buffer as a stream 166 * 167 * @param filters the list of filters to apply 168 * @param buffer the buffer to filter 169 * @param len the size of the buffer 170 * @param target the stream into which the data will be written 171 */ 172 GIT_EXTERN(int) git_filter_list_stream_buffer( 173 git_filter_list *filters, 174 const char *buffer, 175 size_t len, 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 218