2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_git_attr_h__
8 #define INCLUDE_git_attr_h__
15 * @brief Git attribute management routines
16 * @defgroup git_attr Git attribute management routines
23 * GIT_ATTR_TRUE checks if an attribute is set on. In core git
24 * parlance, this the value for "Set" attributes.
26 * For example, if the attribute file contains:
30 * Then for file `xyz.c` looking up attribute "foo" gives a value for
31 * which `GIT_ATTR_TRUE(value)` is true.
33 #define GIT_ATTR_IS_TRUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_TRUE)
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").
40 * For example, if the attribute file contains:
44 * Then for file `zyx.h` looking up attribute "foo" gives a value for
45 * which `GIT_ATTR_FALSE(value)` is true.
47 #define GIT_ATTR_IS_FALSE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_FALSE)
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.
54 * For example, if the attribute file contains:
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.
65 #define GIT_ATTR_IS_UNSPECIFIED(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_UNSPECIFIED)
68 * GIT_ATTR_HAS_VALUE checks if an attribute is set to a value (as
69 * opposed to TRUE, FALSE or UNSPECIFIED). This would be the case if
70 * for a file with something like:
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.
77 #define GIT_ATTR_HAS_VALUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_STRING)
80 * Possible states for an attribute
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 */
86 GIT_ATTR_VALUE_STRING
/**< This attribute has a value */
90 * Return the value type for a given attribute.
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
96 * If the attribute has a `VALUE` string, it can be accessed normally
97 * as a NULL-terminated C string.
99 * @param attr The attribute
100 * @return the value type for the attribute
102 GIT_EXTERN(git_attr_value_t
) git_attr_value(const char *attr
);
105 * Check attribute flags: Reading values from index and working directory.
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.
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).
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
122 * Check attribute flags: controlling extended attribute behavior.
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.
127 * equivalent) directory for a `gitattributes` file. Passing the
128 * `GIT_ATTR_CHECK_NO_SYSTEM` flag will cause attribute checks to
131 * Passing the `GIT_ATTR_CHECK_INCLUDE_HEAD` flag will use attributes
132 * from a `.gitattributes` file in the repository at the HEAD revision.
134 * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes
135 * from a `.gitattributes` file in a specific commit.
137 #define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2)
138 #define GIT_ATTR_CHECK_INCLUDE_HEAD (1 << 3)
139 #define GIT_ATTR_CHECK_INCLUDE_COMMIT (1 << 4)
142 * An options structure for querying attributes.
145 unsigned int version
;
147 /** A combination of GIT_ATTR_CHECK flags */
150 #ifdef GIT_DEPRECATE_HARD
157 * The commit to load attributes from, when
158 * `GIT_ATTR_CHECK_INCLUDE_COMMIT` is specified.
160 git_oid attr_commit_id
;
163 #define GIT_ATTR_OPTIONS_VERSION 1
164 #define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION}
167 * Look up the value of one git attribute for path.
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.
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.
180 * @return 0 or an error code.
182 GIT_EXTERN(int) git_attr_get(
183 const char **value_out
,
184 git_repository
*repo
,
190 * Look up the value of one git attribute for path with extended options.
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.
203 * @return 0 or an error code.
205 GIT_EXTERN(int) git_attr_get_ext(
206 const char **value_out
,
207 git_repository
*repo
,
208 git_attr_options
*opts
,
213 * Look up a list of git attributes for path.
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.
219 * For example, you might write:
221 * const char *attrs[] = { "crlf", "diff", "foo" };
222 * const char **values[3];
223 * git_attr_get_many(values, repo, 0, "my/fun/file.c", 3, attrs);
225 * Then you could loop through the 3 values to get the settings for
226 * the three attributes you asked about.
228 * @param values_out An array of num_attr entries that will have string
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).
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.
240 * @return 0 or an error code.
242 GIT_EXTERN(int) git_attr_get_many(
243 const char **values_out
,
244 git_repository
*repo
,
251 * Look up a list of git attributes for path with extended options.
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.
265 * @return 0 or an error code.
267 GIT_EXTERN(int) git_attr_get_many_ext(
268 const char **values_out
,
269 git_repository
*repo
,
270 git_attr_options
*opts
,
276 * The callback used with git_attr_foreach.
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
282 * @see git_attr_foreach.
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.
291 typedef int GIT_CALLBACK(git_attr_foreach_cb
)(const char *name
, const char *value
, void *payload
);
294 * Loop over all the git attributes for a path.
296 * @param repo The repository containing the path.
297 * @param flags A combination of GIT_ATTR_CHECK... flags.
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).
301 * @param callback Function to invoke on each attribute name and value.
302 * See git_attr_foreach_cb.
303 * @param payload Passed on as extra parameter to callback function.
304 * @return 0 on success, non-zero callback return value, or error code
306 GIT_EXTERN(int) git_attr_foreach(
307 git_repository
*repo
,
310 git_attr_foreach_cb callback
,
314 * Loop over all the git attributes for a path with extended options.
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
326 GIT_EXTERN(int) git_attr_foreach_ext(
327 git_repository
*repo
,
328 git_attr_options
*opts
,
330 git_attr_foreach_cb callback
,
334 * Flush the gitattributes cache.
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.
341 * @param repo The repository containing the gitattributes cache
342 * @return 0 on success, or an error code
344 GIT_EXTERN(int) git_attr_cache_flush(
345 git_repository
*repo
);
348 * Add a macro definition.
350 * Macros will automatically be loaded from the top level `.gitattributes`
351 * file of the repository (plus the built-in "binary" macro). This
352 * function allows you to add others. For example, to add the default
353 * macro, you would call:
355 * git_attr_add_macro(repo, "binary", "-diff -crlf");
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.
362 GIT_EXTERN(int) git_attr_add_macro(
363 git_repository
*repo
,