]>
Commit | Line | Data |
---|---|---|
d0bfd026 JH |
1 | #ifndef ATTR_H |
2 | #define ATTR_H | |
3 | ||
3a1b3415 HW |
4 | /** |
5 | * gitattributes mechanism gives a uniform way to associate various attributes | |
6 | * to set of paths. | |
7 | * | |
8 | * | |
9 | * Querying Specific Attributes | |
10 | * ---------------------------- | |
11 | * | |
12 | * - Prepare `struct attr_check` using attr_check_initl() function, enumerating | |
13 | * the names of attributes whose values you are interested in, terminated with | |
14 | * a NULL pointer. Alternatively, an empty `struct attr_check` can be | |
15 | * prepared by calling `attr_check_alloc()` function and then attributes you | |
16 | * want to ask about can be added to it with `attr_check_append()` function. | |
17 | * | |
18 | * - Call `git_check_attr()` to check the attributes for the path. | |
19 | * | |
20 | * - Inspect `attr_check` structure to see how each of the attribute in the | |
21 | * array is defined for the path. | |
22 | * | |
23 | * | |
24 | * Example | |
25 | * ------- | |
26 | * | |
27 | * To see how attributes "crlf" and "ident" are set for different paths. | |
28 | * | |
29 | * - Prepare a `struct attr_check` with two elements (because we are checking | |
30 | * two attributes): | |
31 | * | |
32 | * ------------ | |
33 | * static struct attr_check *check; | |
34 | * static void setup_check(void) | |
35 | * { | |
36 | * if (check) | |
37 | * return; // already done | |
38 | * check = attr_check_initl("crlf", "ident", NULL); | |
39 | * } | |
40 | * ------------ | |
41 | * | |
42 | * - Call `git_check_attr()` with the prepared `struct attr_check`: | |
43 | * | |
44 | * ------------ | |
45 | * const char *path; | |
46 | * | |
47 | * setup_check(); | |
44451a2e | 48 | * git_check_attr(&the_index, path, check); |
3a1b3415 HW |
49 | * ------------ |
50 | * | |
51 | * - Act on `.value` member of the result, left in `check->items[]`: | |
52 | * | |
53 | * ------------ | |
54 | * const char *value = check->items[0].value; | |
55 | * | |
56 | * if (ATTR_TRUE(value)) { | |
57 | * The attribute is Set, by listing only the name of the | |
58 | * attribute in the gitattributes file for the path. | |
59 | * } else if (ATTR_FALSE(value)) { | |
60 | * The attribute is Unset, by listing the name of the | |
61 | * attribute prefixed with a dash - for the path. | |
62 | * } else if (ATTR_UNSET(value)) { | |
63 | * The attribute is neither set nor unset for the path. | |
64 | * } else if (!strcmp(value, "input")) { | |
65 | * If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is | |
66 | * true, the value is a string set in the gitattributes | |
67 | * file for the path by saying "attr=value". | |
68 | * } else if (... other check using value as string ...) { | |
69 | * ... | |
70 | * } | |
71 | * ------------ | |
72 | * | |
73 | * To see how attributes in argv[] are set for different paths, only | |
74 | * the first step in the above would be different. | |
75 | * | |
76 | * ------------ | |
77 | * static struct attr_check *check; | |
78 | * static void setup_check(const char **argv) | |
79 | * { | |
80 | * check = attr_check_alloc(); | |
81 | * while (*argv) { | |
82 | * struct git_attr *attr = git_attr(*argv); | |
83 | * attr_check_append(check, attr); | |
84 | * argv++; | |
85 | * } | |
86 | * } | |
87 | * ------------ | |
88 | * | |
89 | * | |
90 | * Querying All Attributes | |
91 | * ----------------------- | |
92 | * | |
93 | * To get the values of all attributes associated with a file: | |
94 | * | |
95 | * - Prepare an empty `attr_check` structure by calling `attr_check_alloc()`. | |
96 | * | |
97 | * - Call `git_all_attrs()`, which populates the `attr_check` with the | |
98 | * attributes attached to the path. | |
99 | * | |
100 | * - Iterate over the `attr_check.items[]` array to examine the attribute | |
101 | * names and values. The name of the attribute described by an | |
102 | * `attr_check.items[]` object can be retrieved via | |
103 | * `git_attr_name(check->items[i].attr)`. (Please note that no items will be | |
104 | * returned for unset attributes, so `ATTR_UNSET()` will return false for all | |
105 | * returned `attr_check.items[]` objects.) | |
106 | * | |
107 | * - Free the `attr_check` struct by calling `attr_check_free()`. | |
108 | */ | |
109 | ||
dfa6b32b PS |
110 | /** |
111 | * The maximum line length for a gitattributes file. If the line exceeds this | |
112 | * length we will ignore it. | |
113 | */ | |
114 | #define ATTR_MAX_LINE_LENGTH 2048 | |
115 | ||
3c50032f PS |
116 | /** |
117 | * The maximum size of the giattributes file. If the file exceeds this size we | |
118 | * will ignore it. | |
119 | */ | |
120 | #define ATTR_MAX_FILE_SIZE (100 * 1024 * 1024) | |
121 | ||
7a400a2c NTND |
122 | struct index_state; |
123 | ||
3a1b3415 HW |
124 | /** |
125 | * An attribute is an opaque object that is identified by its name. Pass the | |
126 | * name to `git_attr()` function to obtain the object of this type. | |
127 | * The internal representation of this structure is of no interest to the | |
128 | * calling programs. The name of the attribute can be retrieved by calling | |
129 | * `git_attr_name()`. | |
130 | */ | |
d0bfd026 JH |
131 | struct git_attr; |
132 | ||
dc81cf37 | 133 | /* opaque structures used internally for attribute collection */ |
685b2925 | 134 | struct all_attrs_item; |
dc81cf37 | 135 | struct attr_stack; |
685b2925 | 136 | |
44451a2e JC |
137 | /* |
138 | * The textual object name for the tree-ish used by git_check_attr() | |
139 | * to read attributes from (instead of from the working tree). | |
140 | */ | |
141 | void set_git_attr_source(const char *); | |
142 | ||
a5e92abd JH |
143 | /* |
144 | * Given a string, return the gitattribute object that | |
145 | * corresponds to it. | |
146 | */ | |
e810e063 | 147 | const struct git_attr *git_attr(const char *); |
d0bfd026 | 148 | |
515106fa | 149 | /* Internal use */ |
a5e92abd JH |
150 | extern const char git_attr__true[]; |
151 | extern const char git_attr__false[]; | |
515106fa | 152 | |
3a1b3415 HW |
153 | /** |
154 | * Attribute Values | |
155 | * ---------------- | |
156 | * | |
157 | * An attribute for a path can be in one of four states: Set, Unset, Unspecified | |
158 | * or set to a string, and `.value` member of `struct attr_check_item` records | |
159 | * it. The three macros check these, if none of them returns true, `.value` | |
160 | * member points at a string value of the attribute for the path. | |
161 | */ | |
162 | ||
163 | /* Returns true if the attribute is Set for the path. */ | |
a5e92abd | 164 | #define ATTR_TRUE(v) ((v) == git_attr__true) |
3a1b3415 HW |
165 | |
166 | /* Returns true if the attribute is Unset for the path. */ | |
a5e92abd | 167 | #define ATTR_FALSE(v) ((v) == git_attr__false) |
3a1b3415 HW |
168 | |
169 | /* Returns true if the attribute is Unspecified for the path. */ | |
a5e92abd | 170 | #define ATTR_UNSET(v) ((v) == NULL) |
515106fa | 171 | |
3a1b3415 | 172 | /* This structure represents one attribute and its value. */ |
7bd18054 | 173 | struct attr_check_item { |
ec4d77aa | 174 | const struct git_attr *attr; |
a5e92abd | 175 | const char *value; |
d0bfd026 JH |
176 | }; |
177 | ||
3a1b3415 HW |
178 | /** |
179 | * This structure represents a collection of `attr_check_item`. It is passed to | |
180 | * `git_check_attr()` function, specifying the attributes to check, and | |
181 | * receives their values. | |
182 | */ | |
37293768 JH |
183 | struct attr_check { |
184 | int nr; | |
185 | int alloc; | |
186 | struct attr_check_item *items; | |
685b2925 BW |
187 | int all_attrs_nr; |
188 | struct all_attrs_item *all_attrs; | |
dc81cf37 | 189 | struct attr_stack *stack; |
37293768 JH |
190 | }; |
191 | ||
c30f2e20 NTND |
192 | struct attr_check *attr_check_alloc(void); |
193 | struct attr_check *attr_check_initl(const char *, ...); | |
194 | struct attr_check *attr_check_dup(const struct attr_check *check); | |
37293768 | 195 | |
c30f2e20 NTND |
196 | struct attr_check_item *attr_check_append(struct attr_check *check, |
197 | const struct git_attr *attr); | |
37293768 | 198 | |
c30f2e20 NTND |
199 | void attr_check_reset(struct attr_check *check); |
200 | void attr_check_clear(struct attr_check *check); | |
201 | void attr_check_free(struct attr_check *check); | |
37293768 | 202 | |
352404ac MH |
203 | /* |
204 | * Return the name of the attribute represented by the argument. The | |
205 | * return value is a pointer to a null-delimited string that is part | |
206 | * of the internal data structure; it should not be modified or freed. | |
207 | */ | |
c30f2e20 | 208 | const char *git_attr_name(const struct git_attr *); |
352404ac | 209 | |
847a9e5d | 210 | void git_check_attr(struct index_state *istate, |
44451a2e | 211 | const char *path, |
47cfc9bd | 212 | struct attr_check *check); |
d0bfd026 | 213 | |
ee548df3 | 214 | /* |
7f864111 JH |
215 | * Retrieve all attributes that apply to the specified path. |
216 | * check holds the attributes and their values. | |
ee548df3 | 217 | */ |
44451a2e | 218 | void git_all_attrs(struct index_state *istate, |
7a400a2c | 219 | const char *path, struct attr_check *check); |
ee548df3 | 220 | |
06f33c17 JH |
221 | enum git_attr_direction { |
222 | GIT_ATTR_CHECKIN, | |
4191e80a | 223 | GIT_ATTR_CHECKOUT, |
4b05548f | 224 | GIT_ATTR_INDEX |
06f33c17 | 225 | }; |
c4500e25 | 226 | void git_attr_set_direction(enum git_attr_direction new_direction); |
06f33c17 | 227 | |
c30f2e20 | 228 | void attr_start(void); |
1a600b75 | 229 | |
15780bb4 | 230 | /* Return the system gitattributes file. */ |
231 | const char *git_attr_system_file(void); | |
232 | ||
233 | /* Return the global gitattributes file, if any. */ | |
234 | const char *git_attr_global_file(void); | |
235 | ||
236 | /* Return whether the system gitattributes file is enabled and should be used. */ | |
237 | int git_attr_system_is_enabled(void); | |
238 | ||
9f9c40cf JC |
239 | extern const char *git_attr_tree; |
240 | ||
d0bfd026 | 241 | #endif /* ATTR_H */ |