]>
Commit | Line | Data |
---|---|---|
ee1f0b1a | 1 | /* |
5e0de328 | 2 | * Copyright (C) 2009-2012 the libgit2 contributors |
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 | */ | |
c63793ee | 33 | #define GIT_ATTR_TRUE(attr) ((attr) == git_attr__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 | */ | |
c63793ee | 47 | #define GIT_ATTR_FALSE(attr) ((attr) == git_attr__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 | */ | |
65 | #define GIT_ATTR_UNSPECIFIED(attr) (!(attr) || (attr) == git_attr__unset) | |
66 | ||
67 | /** | |
68 | * GIT_ATTR_SET_TO_VALUE checks if an attribute is set to a value (as | |
69 | * opposied to TRUE, FALSE or UNSPECIFIED). This would be the case if | |
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 | */ | |
77 | #define GIT_ATTR_SET_TO_VALUE(attr) \ | |
78 | ((attr) && (attr) != git_attr__unset && \ | |
79 | (attr) != git_attr__true && (attr) != git_attr__false) | |
ee1f0b1a | 80 | |
c63793ee VM |
81 | GIT_EXTERN(const char *) git_attr__true; |
82 | GIT_EXTERN(const char *) git_attr__false; | |
f917481e | 83 | GIT_EXTERN(const char *) git_attr__unset; |
ee1f0b1a | 84 | |
f917481e RB |
85 | /** |
86 | * Check attribute flags: Reading values from index and working directory. | |
87 | * | |
88 | * When checking attributes, it is possible to check attribute files | |
89 | * in both the working directory (if there is one) and the index (if | |
90 | * there is one). You can explicitly choose where to check and in | |
91 | * which order using the following flags. | |
92 | * | |
93 | * Core git usually checks the working directory then the index, | |
94 | * except during a checkout when it checks the index first. It will | |
95 | * use index only for creating archives or for a bare repo (if an | |
96 | * index has been specified for the bare repo). | |
97 | */ | |
98 | #define GIT_ATTR_CHECK_FILE_THEN_INDEX 0 | |
99 | #define GIT_ATTR_CHECK_INDEX_THEN_FILE 1 | |
100 | #define GIT_ATTR_CHECK_INDEX_ONLY 2 | |
ee1f0b1a RB |
101 | |
102 | /** | |
f917481e RB |
103 | * Check attribute flags: Using the system attributes file. |
104 | * | |
105 | * Normally, attribute checks include looking in the /etc (or system | |
106 | * equivalent) directory for a `gitattributes` file. Passing this | |
107 | * flag will cause attribute checks to ignore that file. | |
108 | */ | |
109 | #define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2) | |
110 | ||
111 | /** | |
112 | * Look up the value of one git attribute for path. | |
113 | * | |
114 | * @param repo The repository containing the path. | |
115 | * @param flags A combination of GIT_ATTR_CHECK... flags. | |
116 | * @param path The path to check for attributes. Relative paths are | |
117 | * interpreted relative to the repo root. The file does | |
118 | * not have to exist, but if it does not, then it will be | |
119 | * treated as a plain file (not a directory). | |
120 | * @param name The name of the attribute to look up. | |
121 | * @param value Output of the value of the attribute. Use the GIT_ATTR_... | |
122 | * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just | |
123 | * use the string value for attributes set to a value. You | |
124 | * should NOT modify or free this value. | |
ee1f0b1a RB |
125 | */ |
126 | GIT_EXTERN(int) git_attr_get( | |
f917481e RB |
127 | git_repository *repo, |
128 | uint32_t flags, | |
129 | const char *path, | |
130 | const char *name, | |
ee1f0b1a RB |
131 | const char **value); |
132 | ||
133 | /** | |
f917481e RB |
134 | * Look up a list of git attributes for path. |
135 | * | |
136 | * Use this if you have a known list of attributes that you want to | |
137 | * look up in a single call. This is somewhat more efficient than | |
138 | * calling `git_attr_get()` multiple times. | |
139 | * | |
140 | * For example, you might write: | |
141 | * | |
142 | * const char *attrs[] = { "crlf", "diff", "foo" }; | |
143 | * const char **values[3]; | |
144 | * git_attr_get_many(repo, 0, "my/fun/file.c", 3, attrs, values); | |
145 | * | |
146 | * Then you could loop through the 3 values to get the settings for | |
147 | * the three attributes you asked about. | |
148 | * | |
149 | * @param repo The repository containing the path. | |
150 | * @param flags A combination of GIT_ATTR_CHECK... flags. | |
151 | * @param path The path inside the repo to check attributes. This | |
152 | * does not have to exist, but if it does not, then | |
153 | * it will be treated as a plain file (i.e. not a directory). | |
154 | * @param num_attr The number of attributes being looked up | |
155 | * @param names An array of num_attr strings containing attribute names. | |
156 | * @param values An array of num_attr entries that will have string | |
157 | * pointers written into it for the values of the attributes. | |
158 | * You should not modify or free the values that are written | |
159 | * into this array (although of course, you should free the | |
160 | * array itself if you allocated it). | |
ee1f0b1a RB |
161 | */ |
162 | GIT_EXTERN(int) git_attr_get_many( | |
f917481e RB |
163 | git_repository *repo, |
164 | uint32_t flags, | |
165 | const char *path, | |
166 | size_t num_attr, | |
167 | const char **names, | |
ee1f0b1a RB |
168 | const char **values); |
169 | ||
170 | /** | |
f917481e RB |
171 | * Loop over all the git attributes for a path. |
172 | * | |
173 | * @param repo The repository containing the path. | |
174 | * @param flags A combination of GIT_ATTR_CHECK... flags. | |
175 | * @param path The path inside the repo to check attributes. This | |
176 | * does not have to exist, but if it does not, then | |
177 | * it will be treated as a plain file (i.e. not a directory). | |
178 | * @param callback The function that will be invoked on each attribute | |
179 | * and attribute value. The name parameter will be the name | |
180 | * of the attribute and the value will be the value it is | |
181 | * set to, including possibly NULL if the attribute is | |
182 | * explicitly set to UNSPECIFIED using the ! sign. This | |
183 | * will be invoked only once per attribute name, even if | |
184 | * there are multiple rules for a given file. The highest | |
185 | * priority rule will be used. | |
186 | * @param payload Passed on as extra parameter to callback function. | |
ee1f0b1a RB |
187 | */ |
188 | GIT_EXTERN(int) git_attr_foreach( | |
f917481e RB |
189 | git_repository *repo, |
190 | uint32_t flags, | |
191 | const char *path, | |
ee1f0b1a RB |
192 | int (*callback)(const char *name, const char *value, void *payload), |
193 | void *payload); | |
194 | ||
73b51450 RB |
195 | /** |
196 | * Flush the gitattributes cache. | |
197 | * | |
f917481e RB |
198 | * Call this if you have reason to believe that the attributes files on |
199 | * disk no longer match the cached contents of memory. This will cause | |
200 | * the attributes files to be reloaded the next time that an attribute | |
201 | * access function is called. | |
73b51450 RB |
202 | */ |
203 | GIT_EXTERN(void) git_attr_cache_flush( | |
204 | git_repository *repo); | |
205 | ||
206 | /** | |
207 | * Add a macro definition. | |
208 | * | |
f917481e | 209 | * Macros will automatically be loaded from the top level `.gitattributes` |
73b51450 RB |
210 | * file of the repository (plus the build-in "binary" macro). This |
211 | * function allows you to add others. For example, to add the default | |
212 | * macro, you would call: | |
213 | * | |
214 | * git_attr_add_macro(repo, "binary", "-diff -crlf"); | |
215 | */ | |
216 | GIT_EXTERN(int) git_attr_add_macro( | |
217 | git_repository *repo, | |
218 | const char *name, | |
219 | const char *values); | |
220 | ||
ee1f0b1a RB |
221 | /** @} */ |
222 | GIT_END_DECL | |
223 | #endif | |
224 |