]>
Commit | Line | Data |
---|---|---|
ee1f0b1a | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
ee1f0b1a RB |
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_attr_h__ | |
8 | #define INCLUDE_git_attr_h__ | |
9 | ||
10 | #include "common.h" | |
11 | #include "types.h" | |
12 | ||
13 | /** | |
14 | * @file git2/attr.h | |
15 | * @brief Git attribute management routines | |
16 | * @defgroup git_attr Git attribute management routines | |
17 | * @ingroup Git | |
18 | * @{ | |
19 | */ | |
20 | GIT_BEGIN_DECL | |
21 | ||
f917481e RB |
22 | /** |
23 | * GIT_ATTR_TRUE checks if an attribute is set on. In core git | |
24 | * parlance, this the value for "Set" attributes. | |
25 | * | |
26 | * For example, if the attribute file contains: | |
27 | * | |
28 | * *.c foo | |
29 | * | |
30 | * Then for file `xyz.c` looking up attribute "foo" gives a value for | |
31 | * which `GIT_ATTR_TRUE(value)` is true. | |
32 | */ | |
22a2d3d5 | 33 | #define GIT_ATTR_IS_TRUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_TRUE) |
f917481e RB |
34 | |
35 | /** | |
36 | * GIT_ATTR_FALSE checks if an attribute is set off. In core git | |
37 | * parlance, this is the value for attributes that are "Unset" (not to | |
38 | * be confused with values that a "Unspecified"). | |
39 | * | |
40 | * For example, if the attribute file contains: | |
41 | * | |
42 | * *.h -foo | |
43 | * | |
44 | * Then for file `zyx.h` looking up attribute "foo" gives a value for | |
45 | * which `GIT_ATTR_FALSE(value)` is true. | |
46 | */ | |
22a2d3d5 | 47 | #define GIT_ATTR_IS_FALSE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_FALSE) |
f917481e RB |
48 | |
49 | /** | |
50 | * GIT_ATTR_UNSPECIFIED checks if an attribute is unspecified. This | |
51 | * may be due to the attribute not being mentioned at all or because | |
52 | * the attribute was explicitly set unspecified via the `!` operator. | |
53 | * | |
54 | * For example, if the attribute file contains: | |
55 | * | |
56 | * *.c foo | |
57 | * *.h -foo | |
58 | * onefile.c !foo | |
59 | * | |
60 | * Then for `onefile.c` looking up attribute "foo" yields a value with | |
61 | * `GIT_ATTR_UNSPECIFIED(value)` of true. Also, looking up "foo" on | |
62 | * file `onefile.rb` or looking up "bar" on any file will all give | |
63 | * `GIT_ATTR_UNSPECIFIED(value)` of true. | |
64 | */ | |
22a2d3d5 | 65 | #define GIT_ATTR_IS_UNSPECIFIED(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_UNSPECIFIED) |
f917481e RB |
66 | |
67 | /** | |
29e948de | 68 | * GIT_ATTR_HAS_VALUE checks if an attribute is set to a value (as |
d73c94b2 | 69 | * opposed to TRUE, FALSE or UNSPECIFIED). This would be the case if |
f917481e RB |
70 | * for a file with something like: |
71 | * | |
72 | * *.txt eol=lf | |
73 | * | |
74 | * Given this, looking up "eol" for `onefile.txt` will give back the | |
75 | * string "lf" and `GIT_ATTR_SET_TO_VALUE(attr)` will return true. | |
76 | */ | |
22a2d3d5 | 77 | #define GIT_ATTR_HAS_VALUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_STRING) |
ee1f0b1a | 78 | |
18eb6ec8 CMN |
79 | /** |
80 | * Possible states for an attribute | |
81 | */ | |
0c9eacf3 | 82 | typedef enum { |
22a2d3d5 UG |
83 | GIT_ATTR_VALUE_UNSPECIFIED = 0, /**< The attribute has been left unspecified */ |
84 | GIT_ATTR_VALUE_TRUE, /**< The attribute has been set */ | |
85 | GIT_ATTR_VALUE_FALSE, /**< The attribute has been unset */ | |
e579e0f7 | 86 | GIT_ATTR_VALUE_STRING /**< This attribute has a value */ |
22a2d3d5 | 87 | } git_attr_value_t; |
0c9eacf3 | 88 | |
18eb6ec8 CMN |
89 | /** |
90 | * Return the value type for a given attribute. | |
0c9eacf3 | 91 | * |
18eb6ec8 CMN |
92 | * This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute |
93 | * was not set at all), or `VALUE`, if the attribute was set to an | |
94 | * actual string. | |
0c9eacf3 | 95 | * |
18eb6ec8 CMN |
96 | * If the attribute has a `VALUE` string, it can be accessed normally |
97 | * as a NULL-terminated C string. | |
0c9eacf3 | 98 | * |
18eb6ec8 CMN |
99 | * @param attr The attribute |
100 | * @return the value type for the attribute | |
0c9eacf3 | 101 | */ |
22a2d3d5 | 102 | GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr); |
ee1f0b1a | 103 | |
f917481e RB |
104 | /** |
105 | * Check attribute flags: Reading values from index and working directory. | |
106 | * | |
107 | * When checking attributes, it is possible to check attribute files | |
108 | * in both the working directory (if there is one) and the index (if | |
109 | * there is one). You can explicitly choose where to check and in | |
110 | * which order using the following flags. | |
111 | * | |
112 | * Core git usually checks the working directory then the index, | |
113 | * except during a checkout when it checks the index first. It will | |
114 | * use index only for creating archives or for a bare repo (if an | |
115 | * index has been specified for the bare repo). | |
116 | */ | |
117 | #define GIT_ATTR_CHECK_FILE_THEN_INDEX 0 | |
118 | #define GIT_ATTR_CHECK_INDEX_THEN_FILE 1 | |
119 | #define GIT_ATTR_CHECK_INDEX_ONLY 2 | |
ee1f0b1a RB |
120 | |
121 | /** | |
22a2d3d5 | 122 | * Check attribute flags: controlling extended attribute behavior. |
f917481e RB |
123 | * |
124 | * Normally, attribute checks include looking in the /etc (or system | |
125 | * equivalent) directory for a `gitattributes` file. Passing this | |
126 | * flag will cause attribute checks to ignore that file. | |
22a2d3d5 UG |
127 | * equivalent) directory for a `gitattributes` file. Passing the |
128 | * `GIT_ATTR_CHECK_NO_SYSTEM` flag will cause attribute checks to | |
129 | * ignore that file. | |
130 | * | |
131 | * Passing the `GIT_ATTR_CHECK_INCLUDE_HEAD` flag will use attributes | |
132 | * from a `.gitattributes` file in the repository at the HEAD revision. | |
c25aa7cd PP |
133 | * |
134 | * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes | |
135 | * from a `.gitattributes` file in a specific commit. | |
f917481e | 136 | */ |
22a2d3d5 UG |
137 | #define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2) |
138 | #define GIT_ATTR_CHECK_INCLUDE_HEAD (1 << 3) | |
c25aa7cd PP |
139 | #define GIT_ATTR_CHECK_INCLUDE_COMMIT (1 << 4) |
140 | ||
141 | /** | |
142 | * An options structure for querying attributes. | |
143 | */ | |
144 | typedef struct { | |
145 | unsigned int version; | |
146 | ||
147 | /** A combination of GIT_ATTR_CHECK flags */ | |
148 | unsigned int flags; | |
149 | ||
150 | #ifdef GIT_DEPRECATE_HARD | |
151 | void *reserved; | |
152 | #else | |
153 | git_oid *commit_id; | |
154 | #endif | |
155 | ||
156 | /** | |
157 | * The commit to load attributes from, when | |
158 | * `GIT_ATTR_CHECK_INCLUDE_COMMIT` is specified. | |
159 | */ | |
160 | git_oid attr_commit_id; | |
161 | } git_attr_options; | |
162 | ||
163 | #define GIT_ATTR_OPTIONS_VERSION 1 | |
164 | #define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION} | |
f917481e RB |
165 | |
166 | /** | |
167 | * Look up the value of one git attribute for path. | |
168 | * | |
29e948de VM |
169 | * @param value_out Output of the value of the attribute. Use the GIT_ATTR_... |
170 | * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just | |
171 | * use the string value for attributes set to a value. You | |
172 | * should NOT modify or free this value. | |
f917481e RB |
173 | * @param repo The repository containing the path. |
174 | * @param flags A combination of GIT_ATTR_CHECK... flags. | |
175 | * @param path The path to check for attributes. Relative paths are | |
176 | * interpreted relative to the repo root. The file does | |
177 | * not have to exist, but if it does not, then it will be | |
178 | * treated as a plain file (not a directory). | |
179 | * @param name The name of the attribute to look up. | |
e579e0f7 | 180 | * @return 0 or an error code. |
ee1f0b1a RB |
181 | */ |
182 | GIT_EXTERN(int) git_attr_get( | |
29e948de | 183 | const char **value_out, |
0cb16fe9 | 184 | git_repository *repo, |
f917481e RB |
185 | uint32_t flags, |
186 | const char *path, | |
29e948de | 187 | const char *name); |
ee1f0b1a | 188 | |
c25aa7cd PP |
189 | /** |
190 | * Look up the value of one git attribute for path with extended options. | |
191 | * | |
192 | * @param value_out Output of the value of the attribute. Use the GIT_ATTR_... | |
193 | * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just | |
194 | * use the string value for attributes set to a value. You | |
195 | * should NOT modify or free this value. | |
196 | * @param repo The repository containing the path. | |
197 | * @param opts The `git_attr_options` to use when querying these attributes. | |
198 | * @param path The path to check for attributes. Relative paths are | |
199 | * interpreted relative to the repo root. The file does | |
200 | * not have to exist, but if it does not, then it will be | |
201 | * treated as a plain file (not a directory). | |
202 | * @param name The name of the attribute to look up. | |
e579e0f7 | 203 | * @return 0 or an error code. |
c25aa7cd PP |
204 | */ |
205 | GIT_EXTERN(int) git_attr_get_ext( | |
206 | const char **value_out, | |
207 | git_repository *repo, | |
208 | git_attr_options *opts, | |
209 | const char *path, | |
210 | const char *name); | |
211 | ||
ee1f0b1a | 212 | /** |
f917481e RB |
213 | * Look up a list of git attributes for path. |
214 | * | |
215 | * Use this if you have a known list of attributes that you want to | |
216 | * look up in a single call. This is somewhat more efficient than | |
217 | * calling `git_attr_get()` multiple times. | |
218 | * | |
219 | * For example, you might write: | |
220 | * | |
221 | * const char *attrs[] = { "crlf", "diff", "foo" }; | |
222 | * const char **values[3]; | |
29e948de | 223 | * git_attr_get_many(values, repo, 0, "my/fun/file.c", 3, attrs); |
f917481e RB |
224 | * |
225 | * Then you could loop through the 3 values to get the settings for | |
226 | * the three attributes you asked about. | |
227 | * | |
e1967164 | 228 | * @param values_out An array of num_attr entries that will have string |
29e948de VM |
229 | * pointers written into it for the values of the attributes. |
230 | * You should not modify or free the values that are written | |
231 | * into this array (although of course, you should free the | |
232 | * array itself if you allocated it). | |
f917481e RB |
233 | * @param repo The repository containing the path. |
234 | * @param flags A combination of GIT_ATTR_CHECK... flags. | |
235 | * @param path The path inside the repo to check attributes. This | |
236 | * does not have to exist, but if it does not, then | |
237 | * it will be treated as a plain file (i.e. not a directory). | |
238 | * @param num_attr The number of attributes being looked up | |
239 | * @param names An array of num_attr strings containing attribute names. | |
e579e0f7 | 240 | * @return 0 or an error code. |
ee1f0b1a RB |
241 | */ |
242 | GIT_EXTERN(int) git_attr_get_many( | |
29e948de | 243 | const char **values_out, |
b709e951 | 244 | git_repository *repo, |
f917481e RB |
245 | uint32_t flags, |
246 | const char *path, | |
b709e951 | 247 | size_t num_attr, |
29e948de | 248 | const char **names); |
ee1f0b1a | 249 | |
c25aa7cd PP |
250 | /** |
251 | * Look up a list of git attributes for path with extended options. | |
252 | * | |
253 | * @param values_out An array of num_attr entries that will have string | |
254 | * pointers written into it for the values of the attributes. | |
255 | * You should not modify or free the values that are written | |
256 | * into this array (although of course, you should free the | |
257 | * array itself if you allocated it). | |
258 | * @param repo The repository containing the path. | |
259 | * @param opts The `git_attr_options` to use when querying these attributes. | |
260 | * @param path The path inside the repo to check attributes. This | |
261 | * does not have to exist, but if it does not, then | |
262 | * it will be treated as a plain file (i.e. not a directory). | |
263 | * @param num_attr The number of attributes being looked up | |
264 | * @param names An array of num_attr strings containing attribute names. | |
e579e0f7 | 265 | * @return 0 or an error code. |
c25aa7cd PP |
266 | */ |
267 | GIT_EXTERN(int) git_attr_get_many_ext( | |
268 | const char **values_out, | |
269 | git_repository *repo, | |
270 | git_attr_options *opts, | |
271 | const char *path, | |
272 | size_t num_attr, | |
273 | const char **names); | |
274 | ||
ac3d33df JK |
275 | /** |
276 | * The callback used with git_attr_foreach. | |
277 | * | |
278 | * This callback will be invoked only once per attribute name, even if there | |
279 | * are multiple rules for a given file. The highest priority rule will be | |
280 | * used. | |
281 | * | |
282 | * @see git_attr_foreach. | |
283 | * | |
284 | * @param name The attribute name. | |
285 | * @param value The attribute value. May be NULL if the attribute is explicitly | |
286 | * set to UNSPECIFIED using the '!' sign. | |
287 | * @param payload A user-specified pointer. | |
288 | * @return 0 to continue looping, non-zero to stop. This value will be returned | |
289 | * from git_attr_foreach. | |
290 | */ | |
291 | typedef int GIT_CALLBACK(git_attr_foreach_cb)(const char *name, const char *value, void *payload); | |
cfbe4be3 | 292 | |
ee1f0b1a | 293 | /** |
f917481e RB |
294 | * Loop over all the git attributes for a path. |
295 | * | |
296 | * @param repo The repository containing the path. | |
297 | * @param flags A combination of GIT_ATTR_CHECK... flags. | |
5dca2010 RB |
298 | * @param path Path inside the repo to check attributes. This does not have |
299 | * to exist, but if it does not, then it will be treated as a | |
300 | * plain file (i.e. not a directory). | |
ac3d33df JK |
301 | * @param callback Function to invoke on each attribute name and value. |
302 | * See git_attr_foreach_cb. | |
f917481e | 303 | * @param payload Passed on as extra parameter to callback function. |
373cf6a9 | 304 | * @return 0 on success, non-zero callback return value, or error code |
ee1f0b1a RB |
305 | */ |
306 | GIT_EXTERN(int) git_attr_foreach( | |
b709e951 | 307 | git_repository *repo, |
f917481e RB |
308 | uint32_t flags, |
309 | const char *path, | |
cfbe4be3 | 310 | git_attr_foreach_cb callback, |
ee1f0b1a RB |
311 | void *payload); |
312 | ||
c25aa7cd PP |
313 | /** |
314 | * Loop over all the git attributes for a path with extended options. | |
315 | * | |
316 | * @param repo The repository containing the path. | |
317 | * @param opts The `git_attr_options` to use when querying these attributes. | |
318 | * @param path Path inside the repo to check attributes. This does not have | |
319 | * to exist, but if it does not, then it will be treated as a | |
320 | * plain file (i.e. not a directory). | |
321 | * @param callback Function to invoke on each attribute name and value. | |
322 | * See git_attr_foreach_cb. | |
323 | * @param payload Passed on as extra parameter to callback function. | |
324 | * @return 0 on success, non-zero callback return value, or error code | |
325 | */ | |
326 | GIT_EXTERN(int) git_attr_foreach_ext( | |
327 | git_repository *repo, | |
328 | git_attr_options *opts, | |
329 | const char *path, | |
330 | git_attr_foreach_cb callback, | |
331 | void *payload); | |
332 | ||
73b51450 RB |
333 | /** |
334 | * Flush the gitattributes cache. | |
335 | * | |
f917481e RB |
336 | * Call this if you have reason to believe that the attributes files on |
337 | * disk no longer match the cached contents of memory. This will cause | |
338 | * the attributes files to be reloaded the next time that an attribute | |
339 | * access function is called. | |
22a2d3d5 UG |
340 | * |
341 | * @param repo The repository containing the gitattributes cache | |
342 | * @return 0 on success, or an error code | |
73b51450 | 343 | */ |
22a2d3d5 | 344 | GIT_EXTERN(int) git_attr_cache_flush( |
73b51450 RB |
345 | git_repository *repo); |
346 | ||
347 | /** | |
348 | * Add a macro definition. | |
349 | * | |
f917481e | 350 | * Macros will automatically be loaded from the top level `.gitattributes` |
e579e0f7 | 351 | * file of the repository (plus the built-in "binary" macro). This |
73b51450 RB |
352 | * function allows you to add others. For example, to add the default |
353 | * macro, you would call: | |
354 | * | |
b4117e19 | 355 | * git_attr_add_macro(repo, "binary", "-diff -crlf"); |
e579e0f7 MB |
356 | * |
357 | * @param repo The repository to add the macro in. | |
358 | * @param name The name of the macro. | |
359 | * @param values The value for the macro. | |
360 | * @return 0 or an error code. | |
73b51450 RB |
361 | */ |
362 | GIT_EXTERN(int) git_attr_add_macro( | |
363 | git_repository *repo, | |
364 | const char *name, | |
365 | const char *values); | |
366 | ||
ee1f0b1a RB |
367 | /** @} */ |
368 | GIT_END_DECL | |
369 | #endif | |
370 |