Start preparing the API documents.
[git/git.git] / Documentation / technical / api-gitattributes.txt
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.
14 Pass the name and its length to `git_attr()` function to obtain
15 the object of this type. The internal representation of this
16 structure is of no interest to the calling programs.
17
18 `struct git_attr_check`::
19
20 This structure represents a set of attributes to check in a call
21 to `git_checkattr()` function, and receives the results.
22
23
24 Calling Sequence
25 ----------------
26
27 * Prepare an array of `struct git_attr_check` to define the list of
28 attributes you would want to check. To populate this array, you would
29 need to define necessary attributes by calling `git_attr()` function.
30
31 * Call git_checkattr() to check the attributes for the path.
32
33 * Inspect `git_attr_check` structure to see how each of the attribute in
34 the array is defined for the path.
35
36
37 Attribute Values
38 ----------------
39
40 An attribute for a path can be in one of four states: Set, Unset,
41 Unspecified or set to a string, and `.value` member of `struct
42 git_attr_check` records it. There are three macros to check these:
43
44 `ATTR_TRUE()`::
45
46 Returns true if the attribute is Set for the path.
47
48 `ATTR_FALSE()`::
49
50 Returns true if the attribute is Unset for the path.
51
52 `ATTR_UNSET()`::
53
54 Returns true if the attribute is Unspecified for the path.
55
56 If none of the above returns true, `.value` member points at a string
57 value of the attribute for the path.
58
59
60 Example
61 -------
62
63 To see how attributes "crlf" and "indent" are set for different paths.
64
65 . Prepare an array of `struct git_attr_check` with two elements (because
66 we are checking two attributes). Initialize their `attr` member with
67 pointers to `struct git_attr` obtained by calling `git_attr()`:
68
69 ------------
70 static struct git_attr_check check[2];
71 static void setup_check(void)
72 {
73 if (check[0].attr)
74 return; /* already done */
75 check[0].attr = git_attr("crlf", 4);
76 check[1].attr = git_attr("ident", 5);
77 }
78 ------------
79
80 . Call `git_checkattr()` with the prepared array of `struct git_attr_check`:
81
82 ------------
83 const char *path;
84
85 setup_check();
86 git_checkattr(path, ARRAY_SIZE(check), check);
87 ------------
88
89 . Act on `.value` member of the result, left in `check[]`:
90
91 ------------
92 const char *value = check[0].value;
93
94 if (ATTR_TRUE(value)) {
95 The attribute is Set, by listing only the name of the
96 attribute in the gitattributes file for the path.
97 } else if (ATTR_FALSE(value)) {
98 The attribute is Unset, by listing the name of the
99 attribute prefixed with a dash - for the path.
100 } else if (ATTR_UNSET(value)) {
101 The attribute is not set nor unset for the path.
102 } else if (!strcmp(value, "input")) {
103 If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is
104 true, the value is a string set in the gitattributes
105 file for the path by saying "attr=value".
106 } else if (... other check using value as string ...) {
107 ...
108 }
109 ------------
110
111 (JC)