]>
Commit | Line | Data |
---|---|---|
530e741c JH |
1 | gitattributes API |
2 | ================= | |
3 | ||
4 | gitattributes mechanism gives a uniform way to associate various | |
5 | attributes to set of paths. | |
6 | ||
7 | ||
8 | Data Structure | |
9 | -------------- | |
10 | ||
11 | `struct git_attr`:: | |
12 | ||
13 | An attribute is an opaque object that is identified by its name. | |
650cfc51 MH |
14 | Pass the name to `git_attr()` function to obtain the object of |
15 | this type. The internal representation of this structure is | |
352404ac MH |
16 | of no interest to the calling programs. The name of the |
17 | attribute can be retrieved by calling `git_attr_name()`. | |
530e741c | 18 | |
1295c215 | 19 | `struct attr_check_item`:: |
530e741c | 20 | |
1295c215 JH |
21 | This structure represents one attribute and its value. |
22 | ||
23 | `struct attr_check`:: | |
24 | ||
25 | This structure represents a collection of `attr_check_item`. | |
26 | It is passed to `git_check_attr()` function, specifying the | |
27 | attributes to check, and receives their values. | |
530e741c JH |
28 | |
29 | ||
530e741c JH |
30 | Attribute Values |
31 | ---------------- | |
32 | ||
33 | An attribute for a path can be in one of four states: Set, Unset, | |
34 | Unspecified or set to a string, and `.value` member of `struct | |
1295c215 | 35 | attr_check_item` records it. There are three macros to check these: |
530e741c JH |
36 | |
37 | `ATTR_TRUE()`:: | |
38 | ||
39 | Returns true if the attribute is Set for the path. | |
40 | ||
41 | `ATTR_FALSE()`:: | |
42 | ||
43 | Returns true if the attribute is Unset for the path. | |
44 | ||
45 | `ATTR_UNSET()`:: | |
46 | ||
47 | Returns true if the attribute is Unspecified for the path. | |
48 | ||
49 | If none of the above returns true, `.value` member points at a string | |
50 | value of the attribute for the path. | |
51 | ||
52 | ||
ee548df3 MH |
53 | Querying Specific Attributes |
54 | ---------------------------- | |
55 | ||
1295c215 JH |
56 | * Prepare `struct attr_check` using attr_check_initl() |
57 | function, enumerating the names of attributes whose values you are | |
58 | interested in, terminated with a NULL pointer. Alternatively, an | |
59 | empty `struct attr_check` can be prepared by calling | |
60 | `attr_check_alloc()` function and then attributes you want to | |
61 | ask about can be added to it with `attr_check_append()` | |
62 | function. | |
ee548df3 | 63 | |
d932f4eb | 64 | * Call `git_check_attr()` to check the attributes for the path. |
ee548df3 | 65 | |
1295c215 JH |
66 | * Inspect `attr_check` structure to see how each of the |
67 | attribute in the array is defined for the path. | |
ee548df3 MH |
68 | |
69 | ||
530e741c JH |
70 | Example |
71 | ------- | |
72 | ||
1295c215 | 73 | To see how attributes "crlf" and "ident" are set for different paths. |
530e741c | 74 | |
1295c215 JH |
75 | . Prepare a `struct attr_check` with two elements (because |
76 | we are checking two attributes): | |
530e741c JH |
77 | |
78 | ------------ | |
1295c215 | 79 | static struct attr_check *check; |
530e741c JH |
80 | static void setup_check(void) |
81 | { | |
1295c215 | 82 | if (check) |
530e741c | 83 | return; /* already done */ |
1295c215 | 84 | check = attr_check_initl("crlf", "ident", NULL); |
530e741c JH |
85 | } |
86 | ------------ | |
87 | ||
1295c215 | 88 | . Call `git_check_attr()` with the prepared `struct attr_check`: |
530e741c JH |
89 | |
90 | ------------ | |
91 | const char *path; | |
92 | ||
93 | setup_check(); | |
1295c215 | 94 | git_check_attr(path, check); |
530e741c JH |
95 | ------------ |
96 | ||
1295c215 | 97 | . Act on `.value` member of the result, left in `check->items[]`: |
530e741c JH |
98 | |
99 | ------------ | |
1295c215 | 100 | const char *value = check->items[0].value; |
530e741c JH |
101 | |
102 | if (ATTR_TRUE(value)) { | |
103 | The attribute is Set, by listing only the name of the | |
104 | attribute in the gitattributes file for the path. | |
105 | } else if (ATTR_FALSE(value)) { | |
106 | The attribute is Unset, by listing the name of the | |
107 | attribute prefixed with a dash - for the path. | |
108 | } else if (ATTR_UNSET(value)) { | |
a58088ab | 109 | The attribute is neither set nor unset for the path. |
530e741c JH |
110 | } else if (!strcmp(value, "input")) { |
111 | If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is | |
112 | true, the value is a string set in the gitattributes | |
113 | file for the path by saying "attr=value". | |
114 | } else if (... other check using value as string ...) { | |
115 | ... | |
116 | } | |
117 | ------------ | |
118 | ||
1295c215 JH |
119 | To see how attributes in argv[] are set for different paths, only |
120 | the first step in the above would be different. | |
121 | ||
122 | ------------ | |
123 | static struct attr_check *check; | |
124 | static void setup_check(const char **argv) | |
125 | { | |
126 | check = attr_check_alloc(); | |
127 | while (*argv) { | |
128 | struct git_attr *attr = git_attr(*argv); | |
129 | attr_check_append(check, attr); | |
130 | argv++; | |
131 | } | |
132 | } | |
133 | ------------ | |
134 | ||
ee548df3 MH |
135 | |
136 | Querying All Attributes | |
137 | ----------------------- | |
138 | ||
139 | To get the values of all attributes associated with a file: | |
140 | ||
1295c215 JH |
141 | * Prepare an empty `attr_check` structure by calling |
142 | `attr_check_alloc()`. | |
143 | ||
144 | * Call `git_all_attrs()`, which populates the `attr_check` | |
145 | with the attributes attached to the path. | |
ee548df3 | 146 | |
1295c215 JH |
147 | * Iterate over the `attr_check.items[]` array to examine |
148 | the attribute names and values. The name of the attribute | |
928f0ab4 | 149 | described by an `attr_check.items[]` object can be retrieved via |
1295c215 JH |
150 | `git_attr_name(check->items[i].attr)`. (Please note that no items |
151 | will be returned for unset attributes, so `ATTR_UNSET()` will return | |
152 | false for all returned `attr_check.items[]` objects.) | |
ee548df3 | 153 | |
1295c215 | 154 | * Free the `attr_check` struct by calling `attr_check_free()`. |