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 attr_check_item`:: 20 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. 28 29 30Attribute Values 31---------------- 32 33An attribute for a path can be in one of four states: Set, Unset, 34Unspecified or set to a string, and `.value` member of `struct 35attr_check_item` records it. There are three macros to check these: 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 49If none of the above returns true, `.value` member points at a string 50value of the attribute for the path. 51 52 53Querying Specific Attributes 54---------------------------- 55 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. 63 64* Call `git_check_attr()` to check the attributes for the path. 65 66* Inspect `attr_check` structure to see how each of the 67 attribute in the array is defined for the path. 68 69 70Example 71------- 72 73To see how attributes "crlf" and "ident" are set for different paths. 74 75. Prepare a `struct attr_check` with two elements (because 76 we are checking two attributes): 77 78------------ 79static struct attr_check *check; 80static void setup_check(void) 81{ 82 if (check) 83 return; /* already done */ 84 check = attr_check_initl("crlf", "ident", NULL); 85} 86------------ 87 88. Call `git_check_attr()` with the prepared `struct attr_check`: 89 90------------ 91 const char *path; 92 93 setup_check(); 94 git_check_attr(path, check); 95------------ 96 97. Act on `.value` member of the result, left in `check->items[]`: 98 99------------ 100 const char *value = check->items[0].value; 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)) { 109 The attribute is neither set nor unset for the path. 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 119To see how attributes in argv[] are set for different paths, only 120the first step in the above would be different. 121 122------------ 123static struct attr_check *check; 124static 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 135 136Querying All Attributes 137----------------------- 138 139To get the values of all attributes associated with a file: 140 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. 146 147* Iterate over the `attr_check.items[]` array to examine 148 the attribute names and values. The name of the attribute 149 described by an `attr_check.items[]` object can be retrieved via 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.) 153 154* Free the `attr_check` struct by calling `attr_check_free()`.