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 module libgit2_d.filter; 8 9 10 private static import libgit2_d.buffer; 11 private static import libgit2_d.sys.filter; 12 private static import libgit2_d.types; 13 14 /** 15 * @file git2/filter.h 16 * @brief Git filter APIs 17 * 18 * @ingroup Git 19 * @{ 20 */ 21 extern (C): 22 nothrow @nogc: 23 public: 24 25 /** 26 * Filters are applied in one of two directions: smudging - which is 27 * exporting a file from the Git object database to the working directory, 28 * and cleaning - which is importing a file from the working directory to 29 * the Git object database. These values control which direction of 30 * change is being applied. 31 */ 32 enum git_filter_mode_t 33 { 34 GIT_FILTER_TO_WORKTREE = 0, 35 GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE, 36 GIT_FILTER_TO_ODB = 1, 37 GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB, 38 } 39 40 /** 41 * Filter option flags. 42 */ 43 enum git_filter_flag_t 44 { 45 GIT_FILTER_DEFAULT = 0u, 46 47 /** 48 * Don't error for `safecrlf` violations, allow them to continue. 49 */ 50 GIT_FILTER_ALLOW_UNSAFE = 1u << 0, 51 52 /** 53 * Don't load `/etc/gitattributes` (or the system equivalent) 54 */ 55 GIT_FILTER_NO_SYSTEM_ATTRIBUTES = 1u << 1, 56 57 /** 58 * Load attributes from `.gitattributes` in the root of HEAD 59 */ 60 GIT_FILTER_ATTRIBUTES_FROM_HEAD = 1u << 2, 61 } 62 63 /** 64 * A filter that can transform file data 65 * 66 * This represents a filter that can be used to transform or even replace 67 * file data. Libgit2 includes one built in filter and it is possible to 68 * write your own (see git2/sys/filter.h for information on that). 69 * 70 * The two builtin filters are: 71 * 72 * * "crlf" which uses the complex rules with the "text", "eol", and 73 * "crlf" file attributes to decide how to convert between LF and CRLF 74 * line endings 75 * * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon 76 * checkout and replaced "$Id: <anything>$" with "$Id$" on checkin. 77 */ 78 alias git_filter = libgit2_d.sys.filter.git_filter; 79 80 /** 81 * List of filters to be applied 82 * 83 * This represents a list of filters to be applied to a file / blob. You 84 * can build the list with one call, apply it with another, and dispose it 85 * with a third. In typical usage, there are not many occasions where a 86 * git_filter_list is needed directly since the library will generally 87 * handle conversions for you, but it can be convenient to be able to 88 * build and apply the list sometimes. 89 */ 90 struct git_filter_list; 91 92 /** 93 * Load the filter list for a given path. 94 * 95 * This will return 0 (success) but set the output git_filter_list to null 96 * if no filters are requested for the given file. 97 * 98 * @param filters Output newly created git_filter_list (or null) 99 * @param repo Repository object that contains `path` 100 * @param blob The blob to which the filter will be applied (if known) 101 * @param path Relative path of the file to be filtered 102 * @param mode Filtering direction (WT->ODB or ODB->WT) 103 * @param flags Combination of `git_filter_flag_t` flags 104 * @return 0 on success (which could still return null if no filters are 105 * needed for the requested file), <0 on error 106 */ 107 //GIT_EXTERN 108 int git_filter_list_load(.git_filter_list** filters, libgit2_d.types.git_repository* repo, libgit2_d.types.git_blob* blob, /* can be null */ 109 const (char)* path, .git_filter_mode_t mode, uint flags); 110 111 /** 112 * Query the filter list to see if a given filter (by name) will run. 113 * The built-in filters "crlf" and "ident" can be queried, otherwise this 114 * is the name of the filter specified by the filter attribute. 115 * 116 * This will return 0 if the given filter is not in the list, or 1 if 117 * the filter will be applied. 118 * 119 * @param filters A loaded git_filter_list (or null) 120 * @param name The name of the filter to query 121 * @return 1 if the filter is in the list, 0 otherwise 122 */ 123 //GIT_EXTERN 124 int git_filter_list_contains(.git_filter_list* filters, const (char)* name); 125 126 /** 127 * Apply filter list to a data buffer. 128 * 129 * See `git2/buffer.h` for background on `git_buf` objects. 130 * 131 * If the `in` buffer holds data allocated by libgit2 (i.e. `in_->asize` is 132 * not zero), then it will be overwritten when applying the filters. If 133 * not, then it will be left untouched. 134 * 135 * If there are no filters to apply (or `filters` is null), then the `out` 136 * buffer will reference the `in` buffer data (with `asize` set to zero) 137 * instead of allocating data. This keeps allocations to a minimum, but 138 * it means you have to be careful about freeing the `in` data since `out` 139 * may be pointing to it! 140 * 141 * @param out_ Buffer to store the result of the filtering 142 * @param filters A loaded git_filter_list (or null) 143 * @param in_ Buffer containing the data to filter 144 * @return 0 on success, an error code otherwise 145 */ 146 //GIT_EXTERN 147 int git_filter_list_apply_to_data(libgit2_d.buffer.git_buf* out_, .git_filter_list* filters, libgit2_d.buffer.git_buf* in_); 148 149 /** 150 * Apply a filter list to the contents of a file on disk 151 * 152 * @param out_ buffer into which to store the filtered file 153 * @param filters the list of filters to apply 154 * @param repo the repository in which to perform the filtering 155 * @param path the path of the file to filter, a relative path will be 156 * taken as relative to the workdir 157 */ 158 //GIT_EXTERN 159 int git_filter_list_apply_to_file(libgit2_d.buffer.git_buf* out_, .git_filter_list* filters, libgit2_d.types.git_repository* repo, const (char)* path); 160 161 /** 162 * Apply a filter list to the contents of a blob 163 * 164 * @param out_ buffer into which to store the filtered file 165 * @param filters the list of filters to apply 166 * @param blob the blob to filter 167 */ 168 //GIT_EXTERN 169 int git_filter_list_apply_to_blob(libgit2_d.buffer.git_buf* out_, .git_filter_list* filters, libgit2_d.types.git_blob* blob); 170 171 /** 172 * Apply a filter list to an arbitrary buffer as a stream 173 * 174 * @param filters the list of filters to apply 175 * @param data the buffer to filter 176 * @param target the stream into which the data will be written 177 */ 178 //GIT_EXTERN 179 int git_filter_list_stream_data(.git_filter_list* filters, libgit2_d.buffer.git_buf* data, libgit2_d.types.git_writestream* target); 180 181 /** 182 * Apply a filter list to a file as a stream 183 * 184 * @param filters the list of filters to apply 185 * @param repo the repository in which to perform the filtering 186 * @param path the path of the file to filter, a relative path will be 187 * taken as relative to the workdir 188 * @param target the stream into which the data will be written 189 */ 190 //GIT_EXTERN 191 int git_filter_list_stream_file(.git_filter_list* filters, libgit2_d.types.git_repository* repo, const (char)* path, libgit2_d.types.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 201 int git_filter_list_stream_blob(.git_filter_list* filters, libgit2_d.types.git_blob* blob, libgit2_d.types.git_writestream* target); 202 203 /** 204 * Free a git_filter_list 205 * 206 * @param filters A git_filter_list created by `git_filter_list_load` 207 */ 208 //GIT_EXTERN 209 void git_filter_list_free(.git_filter_list* filters); 210 211 /** @} */