diff options
Diffstat (limited to 'Documentation/technical/api-gitattributes.txt')
| -rw-r--r-- | Documentation/technical/api-gitattributes.txt | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/Documentation/technical/api-gitattributes.txt b/Documentation/technical/api-gitattributes.txt new file mode 100644 index 000000000000..45f0df600fab --- /dev/null +++ b/Documentation/technical/api-gitattributes.txt @@ -0,0 +1,154 @@ +gitattributes API +================= + +gitattributes mechanism gives a uniform way to associate various +attributes to set of paths. + + +Data Structure +-------------- + +`struct git_attr`:: + + An attribute is an opaque object that is identified by its name. + Pass the name to `git_attr()` function to obtain the object of + this type. The internal representation of this structure is + of no interest to the calling programs. The name of the + attribute can be retrieved by calling `git_attr_name()`. + +`struct attr_check_item`:: + + This structure represents one attribute and its value. + +`struct attr_check`:: + + This structure represents a collection of `attr_check_item`. + It is passed to `git_check_attr()` function, specifying the + attributes to check, and receives their values. + + +Attribute Values +---------------- + +An attribute for a path can be in one of four states: Set, Unset, +Unspecified or set to a string, and `.value` member of `struct +attr_check_item` records it. There are three macros to check these: + +`ATTR_TRUE()`:: + + Returns true if the attribute is Set for the path. + +`ATTR_FALSE()`:: + + Returns true if the attribute is Unset for the path. + +`ATTR_UNSET()`:: + + Returns true if the attribute is Unspecified for the path. + +If none of the above returns true, `.value` member points at a string +value of the attribute for the path. + + +Querying Specific Attributes +---------------------------- + +* Prepare `struct attr_check` using attr_check_initl() + function, enumerating the names of attributes whose values you are + interested in, terminated with a NULL pointer. Alternatively, an + empty `struct attr_check` can be prepared by calling + `attr_check_alloc()` function and then attributes you want to + ask about can be added to it with `attr_check_append()` + function. + +* Call `git_check_attr()` to check the attributes for the path. + +* Inspect `attr_check` structure to see how each of the + attribute in the array is defined for the path. + + +Example +------- + +To see how attributes "crlf" and "ident" are set for different paths. + +. Prepare a `struct attr_check` with two elements (because + we are checking two attributes): + +------------ +static struct attr_check *check; +static void setup_check(void) +{ + if (check) + return; /* already done */ + check = attr_check_initl("crlf", "ident", NULL); +} +------------ + +. Call `git_check_attr()` with the prepared `struct attr_check`: + +------------ + const char *path; + + setup_check(); + git_check_attr(path, check); +------------ + +. Act on `.value` member of the result, left in `check->items[]`: + +------------ + const char *value = check->items[0].value; + + if (ATTR_TRUE(value)) { + The attribute is Set, by listing only the name of the + attribute in the gitattributes file for the path. + } else if (ATTR_FALSE(value)) { + The attribute is Unset, by listing the name of the + attribute prefixed with a dash - for the path. + } else if (ATTR_UNSET(value)) { + The attribute is neither set nor unset for the path. + } else if (!strcmp(value, "input")) { + If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is + true, the value is a string set in the gitattributes + file for the path by saying "attr=value". + } else if (... other check using value as string ...) { + ... + } +------------ + +To see how attributes in argv[] are set for different paths, only +the first step in the above would be different. + +------------ +static struct attr_check *check; +static void setup_check(const char **argv) +{ + check = attr_check_alloc(); + while (*argv) { + struct git_attr *attr = git_attr(*argv); + attr_check_append(check, attr); + argv++; + } +} +------------ + + +Querying All Attributes +----------------------- + +To get the values of all attributes associated with a file: + +* Prepare an empty `attr_check` structure by calling + `attr_check_alloc()`. + +* Call `git_all_attrs()`, which populates the `attr_check` + with the attributes attached to the path. + +* Iterate over the `attr_check.items[]` array to examine + the attribute names and values. The name of the attribute + described by an `attr_check.items[]` object can be retrieved via + `git_attr_name(check->items[i].attr)`. (Please note that no items + will be returned for unset attributes, so `ATTR_UNSET()` will return + false for all returned `attr_check.items[]` objects.) + +* Free the `attr_check` struct by calling `attr_check_free()`. |