projects / thirdparty / git.git / blame
| 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. | |
| 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) |