Andrew's git - gitweb.git/blob - Documentation/technical/api-gitattributes.txt

   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 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
  24Calling 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
  37Attribute Values
  38----------------
  39
  40An attribute for a path can be in one of four states: Set, Unset,
  41Unspecified or set to a string, and `.value` member of `struct
  42git_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
  56If none of the above returns true, `.value` member points at a string
  57value of the attribute for the path.
  58
  59
  60Example
  61-------
  62
  63To 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------------
  70static struct git_attr_check check[2];
  71static 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)