1gitattributes API 2================= 3 4gitattributes mechanism gives a uniform way to associate various 5attributes to set of paths. 6 7 8Data 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 to `git_attr()` function to obtain the object of 15 this type. The internal representation of this structure is 16 of no interest to the calling programs. The name of the 17 attribute can be retrieved by calling `git_attr_name()`. 18 19`struct git_attr_check`:: 20 21 This structure represents a set of attributes to check in a call 22 to `git_check_attr()` function, and receives the results. 23 24 25Attribute Values 26---------------- 27 28An attribute for a path can be in one of four states: Set, Unset, 29Unspecified or set to a string, and `.value` member of `struct 30git_attr_check` records it. There are three macros to check these: 31 32`ATTR_TRUE()`:: 33 34 Returns true if the attribute is Set for the path. 35 36`ATTR_FALSE()`:: 37 38 Returns true if the attribute is Unset for the path. 39 40`ATTR_UNSET()`:: 41 42 Returns true if the attribute is Unspecified for the path. 43 44If none of the above returns true, `.value` member points at a string 45value of the attribute for the path. 46 47 48Querying Specific Attributes 49---------------------------- 50 51* Prepare an array of `struct git_attr_check` to define the list of 52 attributes you would want to check. To populate this array, you would 53 need to define necessary attributes by calling `git_attr()` function. 54 55* Call `git_check_attr()` to check the attributes for the path. 56 57* Inspect `git_attr_check` structure to see how each of the attribute in 58 the array is defined for the path. 59 60 61Example 62------- 63 64To see how attributes "crlf" and "indent" are set for different paths. 65 66. Prepare an array of `struct git_attr_check` with two elements (because 67 we are checking two attributes). Initialize their `attr` member with 68 pointers to `struct git_attr` obtained by calling `git_attr()`: 69 70------------ 71static struct git_attr_check check[2]; 72static void setup_check(void) 73{ 74 if (check[0].attr) 75 return; /* already done */ 76 check[0].attr = git_attr("crlf"); 77 check[1].attr = git_attr("ident"); 78} 79------------ 80 81. Call `git_check_attr()` with the prepared array of `struct git_attr_check`: 82 83------------ 84 const char *path; 85 86 setup_check(); 87 git_check_attr(path, ARRAY_SIZE(check), check); 88------------ 89 90. Act on `.value` member of the result, left in `check[]`: 91 92------------ 93 const char *value = check[0].value; 94 95 if (ATTR_TRUE(value)) { 96 The attribute is Set, by listing only the name of the 97 attribute in the gitattributes file for the path. 98 } else if (ATTR_FALSE(value)) { 99 The attribute is Unset, by listing the name of the 100 attribute prefixed with a dash - for the path. 101 } else if (ATTR_UNSET(value)) { 102 The attribute is neither set nor unset for the path. 103 } else if (!strcmp(value, "input")) { 104 If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is 105 true, the value is a string set in the gitattributes 106 file for the path by saying "attr=value". 107 } else if (... other check using value as string ...) { 108 ... 109 } 110------------ 111 112 113Querying All Attributes 114----------------------- 115 116To get the values of all attributes associated with a file: 117 118* Call `git_all_attrs()`, which returns an array of `git_attr_check` 119 structures. 120 121* Iterate over the `git_attr_check` array to examine the attribute 122 names and values. The name of the attribute described by a 123 `git_attr_check` object can be retrieved via 124 `git_attr_name(check[i].attr)`. (Please note that no items will be 125 returned for unset attributes, so `ATTR_UNSET()` will return false 126 for all returned `git_array_check` objects.) 127 128* Free the `git_array_check` array.