`struct git_attr`::
An attribute is an opaque object that is identified by its name.
- Pass the name and its length 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.
+ 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 git_attr_check`::
+`struct attr_check_item`::
- This structure represents a set of attributes to check in a call
- to `git_checkattr()` function, and receives the results.
+ This structure represents one attribute and its value.
+`struct attr_check`::
-Calling Sequence
-----------------
-
-* Prepare an array of `struct git_attr_check` to define the list of
- attributes you would want to check. To populate this array, you would
- need to define necessary attributes by calling `git_attr()` function.
-
-* Call git_checkattr() to check the attributes for the path.
-
-* Inspect `git_attr_check` structure to see how each of the attribute in
- the array is defined for the path.
+ 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
-git_attr_check` records it. There are three macros to check these:
+attr_check_item` records it. There are three macros to check these:
`ATTR_TRUE()`::
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 "indent" are set for different paths.
+To see how attributes "crlf" and "ident" are set for different paths.
-. Prepare an array of `struct git_attr_check` with two elements (because
- we are checking two attributes). Initialize their `attr` member with
- pointers to `struct git_attr` obtained by calling `git_attr()`:
+. Prepare a `struct attr_check` with two elements (because
+ we are checking two attributes):
------------
-static struct git_attr_check check[2];
+static struct attr_check *check;
static void setup_check(void)
{
- if (check[0].attr)
+ if (check)
return; /* already done */
- check[0].attr = git_attr("crlf", 4);
- check[1].attr = git_attr("ident", 5);
+ check = attr_check_initl("crlf", "ident", NULL);
}
------------
-. Call `git_checkattr()` with the prepared array of `struct git_attr_check`:
+. Call `git_check_attr()` with the prepared `struct attr_check`:
------------
const char *path;
setup_check();
- git_checkattr(path, ARRAY_SIZE(check), check);
+ git_check_attr(path, check);
------------
-. Act on `.value` member of the result, left in `check[]`:
+. Act on `.value` member of the result, left in `check->items[]`:
------------
- const char *value = check[0].value;
+ const char *value = check->items[0].value;
if (ATTR_TRUE(value)) {
The attribute is Set, by listing only the name of the
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 not set nor unset for the path.
+ 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
}
------------
-(JC)
+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()`.