]>
Commit | Line | Data |
---|---|---|
0cf77103 RB |
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 { | |
2a7d224f RB |
32 | GIT_FILTER_TO_WORKTREE = 0, |
33 | GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE, | |
34 | GIT_FILTER_TO_ODB = 1, | |
e579e0f7 | 35 | GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB |
0cf77103 RB |
36 | } git_filter_mode_t; |
37 | ||
a295bd2d CMN |
38 | /** |
39 | * Filter option flags. | |
40 | */ | |
5269008c | 41 | typedef enum { |
795eaccd | 42 | GIT_FILTER_DEFAULT = 0u, |
22a2d3d5 UG |
43 | |
44 | /** Don't error for `safecrlf` violations, allow them to continue. */ | |
795eaccd | 45 | GIT_FILTER_ALLOW_UNSAFE = (1u << 0), |
22a2d3d5 UG |
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), | |
c25aa7cd PP |
52 | |
53 | /** | |
54 | * Load attributes from `.gitattributes` in a given commit. | |
55 | * This can only be specified in a `git_filter_options`. | |
56 | */ | |
e579e0f7 | 57 | GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3) |
795eaccd | 58 | } git_filter_flag_t; |
5269008c | 59 | |
c25aa7cd PP |
60 | /** |
61 | * Filtering options | |
62 | */ | |
63 | typedef struct { | |
64 | unsigned int version; | |
65 | ||
66 | /** See `git_filter_flag_t` above */ | |
67 | uint32_t flags; | |
68 | ||
69 | #ifdef GIT_DEPRECATE_HARD | |
70 | void *reserved; | |
71 | #else | |
72 | git_oid *commit_id; | |
73 | #endif | |
74 | ||
75 | /** | |
76 | * The commit to load attributes from, when | |
77 | * `GIT_FILTER_ATTRIBUTES_FROM_COMMIT` is specified. | |
78 | */ | |
79 | git_oid attr_commit_id; | |
80 | } git_filter_options; | |
81 | ||
82 | #define GIT_FILTER_OPTIONS_VERSION 1 | |
83 | #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION} | |
84 | ||
0cf77103 RB |
85 | /** |
86 | * A filter that can transform file data | |
87 | * | |
88 | * This represents a filter that can be used to transform or even replace | |
85d54812 RB |
89 | * file data. Libgit2 includes one built in filter and it is possible to |
90 | * write your own (see git2/sys/filter.h for information on that). | |
91 | * | |
4b11f25a | 92 | * The two builtin filters are: |
0cf77103 RB |
93 | * |
94 | * * "crlf" which uses the complex rules with the "text", "eol", and | |
95 | * "crlf" file attributes to decide how to convert between LF and CRLF | |
96 | * line endings | |
4b11f25a RB |
97 | * * "ident" which replaces "$Id$" in a blob with "$Id: <blob OID>$" upon |
98 | * checkout and replaced "$Id: <anything>$" with "$Id$" on checkin. | |
0cf77103 RB |
99 | */ |
100 | typedef struct git_filter git_filter; | |
101 | ||
2a7d224f RB |
102 | /** |
103 | * List of filters to be applied | |
104 | * | |
105 | * This represents a list of filters to be applied to a file / blob. You | |
106 | * can build the list with one call, apply it with another, and dispose it | |
107 | * with a third. In typical usage, there are not many occasions where a | |
108 | * git_filter_list is needed directly since the library will generally | |
109 | * handle conversions for you, but it can be convenient to be able to | |
110 | * build and apply the list sometimes. | |
111 | */ | |
112 | typedef struct git_filter_list git_filter_list; | |
113 | ||
2a7d224f RB |
114 | /** |
115 | * Load the filter list for a given path. | |
116 | * | |
117 | * This will return 0 (success) but set the output git_filter_list to NULL | |
118 | * if no filters are requested for the given file. | |
119 | * | |
120 | * @param filters Output newly created git_filter_list (or NULL) | |
121 | * @param repo Repository object that contains `path` | |
4b11f25a | 122 | * @param blob The blob to which the filter will be applied (if known) |
2a7d224f RB |
123 | * @param path Relative path of the file to be filtered |
124 | * @param mode Filtering direction (WT->ODB or ODB->WT) | |
795eaccd | 125 | * @param flags Combination of `git_filter_flag_t` flags |
2a7d224f RB |
126 | * @return 0 on success (which could still return NULL if no filters are |
127 | * needed for the requested file), <0 on error | |
128 | */ | |
129 | GIT_EXTERN(int) git_filter_list_load( | |
130 | git_filter_list **filters, | |
131 | git_repository *repo, | |
4b11f25a | 132 | git_blob *blob, /* can be NULL */ |
2a7d224f | 133 | const char *path, |
5269008c | 134 | git_filter_mode_t mode, |
795eaccd | 135 | uint32_t flags); |
2a7d224f | 136 | |
c25aa7cd PP |
137 | /** |
138 | * Load the filter list for a given path. | |
139 | * | |
140 | * This will return 0 (success) but set the output git_filter_list to NULL | |
141 | * if no filters are requested for the given file. | |
142 | * | |
143 | * @param filters Output newly created git_filter_list (or NULL) | |
144 | * @param repo Repository object that contains `path` | |
145 | * @param blob The blob to which the filter will be applied (if known) | |
146 | * @param path Relative path of the file to be filtered | |
147 | * @param mode Filtering direction (WT->ODB or ODB->WT) | |
148 | * @param opts The `git_filter_options` to use when loading filters | |
149 | * @return 0 on success (which could still return NULL if no filters are | |
150 | * needed for the requested file), <0 on error | |
151 | */ | |
152 | GIT_EXTERN(int) git_filter_list_load_ext( | |
153 | git_filter_list **filters, | |
154 | git_repository *repo, | |
155 | git_blob *blob, | |
156 | const char *path, | |
157 | git_filter_mode_t mode, | |
158 | git_filter_options *opts); | |
159 | ||
2eecc288 ET |
160 | /** |
161 | * Query the filter list to see if a given filter (by name) will run. | |
162 | * The built-in filters "crlf" and "ident" can be queried, otherwise this | |
163 | * is the name of the filter specified by the filter attribute. | |
164 | * | |
165 | * This will return 0 if the given filter is not in the list, or 1 if | |
166 | * the filter will be applied. | |
167 | * | |
168 | * @param filters A loaded git_filter_list (or NULL) | |
169 | * @param name The name of the filter to query | |
170 | * @return 1 if the filter is in the list, 0 otherwise | |
171 | */ | |
172 | GIT_EXTERN(int) git_filter_list_contains( | |
173 | git_filter_list *filters, | |
174 | const char *name); | |
175 | ||
2a7d224f RB |
176 | /** |
177 | * Apply filter list to a data buffer. | |
178 | * | |
2a7d224f RB |
179 | * @param out Buffer to store the result of the filtering |
180 | * @param filters A loaded git_filter_list (or NULL) | |
181 | * @param in Buffer containing the data to filter | |
c25aa7cd | 182 | * @param in_len The length of the input buffer |
2a7d224f RB |
183 | * @return 0 on success, an error code otherwise |
184 | */ | |
c25aa7cd | 185 | GIT_EXTERN(int) git_filter_list_apply_to_buffer( |
a9f51e43 | 186 | git_buf *out, |
2a7d224f | 187 | git_filter_list *filters, |
c25aa7cd PP |
188 | const char *in, |
189 | size_t in_len); | |
2a7d224f RB |
190 | |
191 | /** | |
a94d3e68 CMN |
192 | * Apply a filter list to the contents of a file on disk |
193 | * | |
194 | * @param out buffer into which to store the filtered file | |
195 | * @param filters the list of filters to apply | |
196 | * @param repo the repository in which to perform the filtering | |
197 | * @param path the path of the file to filter, a relative path will be | |
198 | * taken as relative to the workdir | |
e579e0f7 | 199 | * @return 0 or an error code. |
2a7d224f RB |
200 | */ |
201 | GIT_EXTERN(int) git_filter_list_apply_to_file( | |
a9f51e43 | 202 | git_buf *out, |
2a7d224f RB |
203 | git_filter_list *filters, |
204 | git_repository *repo, | |
205 | const char *path); | |
206 | ||
207 | /** | |
a94d3e68 CMN |
208 | * Apply a filter list to the contents of a blob |
209 | * | |
210 | * @param out buffer into which to store the filtered file | |
211 | * @param filters the list of filters to apply | |
212 | * @param blob the blob to filter | |
e579e0f7 | 213 | * @return 0 or an error code. |
2a7d224f RB |
214 | */ |
215 | GIT_EXTERN(int) git_filter_list_apply_to_blob( | |
a9f51e43 | 216 | git_buf *out, |
2a7d224f RB |
217 | git_filter_list *filters, |
218 | git_blob *blob); | |
219 | ||
a94d3e68 CMN |
220 | /** |
221 | * Apply a filter list to an arbitrary buffer as a stream | |
222 | * | |
223 | * @param filters the list of filters to apply | |
c25aa7cd PP |
224 | * @param buffer the buffer to filter |
225 | * @param len the size of the buffer | |
a94d3e68 | 226 | * @param target the stream into which the data will be written |
e579e0f7 | 227 | * @return 0 or an error code. |
a94d3e68 | 228 | */ |
c25aa7cd | 229 | GIT_EXTERN(int) git_filter_list_stream_buffer( |
fbdc9db3 | 230 | git_filter_list *filters, |
c25aa7cd PP |
231 | const char *buffer, |
232 | size_t len, | |
b75f15aa | 233 | git_writestream *target); |
fbdc9db3 | 234 | |
a94d3e68 CMN |
235 | /** |
236 | * Apply a filter list to a file as a stream | |
237 | * | |
238 | * @param filters the list of filters to apply | |
239 | * @param repo the repository in which to perform the filtering | |
240 | * @param path the path of the file to filter, a relative path will be | |
241 | * taken as relative to the workdir | |
242 | * @param target the stream into which the data will be written | |
e579e0f7 | 243 | * @return 0 or an error code. |
a94d3e68 | 244 | */ |
fbdc9db3 ET |
245 | GIT_EXTERN(int) git_filter_list_stream_file( |
246 | git_filter_list *filters, | |
247 | git_repository *repo, | |
248 | const char *path, | |
b75f15aa | 249 | git_writestream *target); |
fbdc9db3 | 250 | |
a94d3e68 CMN |
251 | /** |
252 | * Apply a filter list to a blob as a stream | |
253 | * | |
254 | * @param filters the list of filters to apply | |
255 | * @param blob the blob to filter | |
256 | * @param target the stream into which the data will be written | |
e579e0f7 | 257 | * @return 0 or an error code. |
a94d3e68 | 258 | */ |
fbdc9db3 ET |
259 | GIT_EXTERN(int) git_filter_list_stream_blob( |
260 | git_filter_list *filters, | |
261 | git_blob *blob, | |
b75f15aa | 262 | git_writestream *target); |
fbdc9db3 | 263 | |
2a7d224f RB |
264 | /** |
265 | * Free a git_filter_list | |
266 | * | |
267 | * @param filters A git_filter_list created by `git_filter_list_load` | |
268 | */ | |
269 | GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters); | |
270 | ||
271 | ||
0cf77103 RB |
272 | GIT_END_DECL |
273 | ||
274 | /** @} */ | |
275 | ||
276 | #endif |