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 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.
struct git_attr_check: This structure represents a set of attributes to check in a call to git_checkattr() function, and receives the results.

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.

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_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.

Example

To see how attributes "crlf" and "indent" 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():

static struct git_attr_check check[2];
static void setup_check(void)
{
        if (check[0].attr)
                return; /* already done */
        check[0].attr = git_attr("crlf", 4);
        check[1].attr = git_attr("ident", 5);
}

Call git_checkattr() with the prepared array of struct git_attr_check:

        const char *path;

        setup_check();
        git_checkattr(path, ARRAY_SIZE(check), check);

Act on .value member of the result, left in check[]:

        const char *value = check[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 not 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 ...) {
                ...
        }

(JC)