attr.h

   1 #ifndef ATTR_H
   2 #define ATTR_H
   3
   4 /**
   5  * gitattributes mechanism gives a uniform way to associate various attributes
   6  * to set of paths.
   7  *
   8  *
   9  * Querying Specific Attributes
  10  * ----------------------------
  11  *
  12  * - Prepare `struct attr_check` using attr_check_initl() function, enumerating
  13  *   the names of attributes whose values you are interested in, terminated with
  14  *   a NULL pointer.  Alternatively, an empty `struct attr_check` can be
  15  *   prepared by calling `attr_check_alloc()` function and then attributes you
  16  *   want to ask about can be added to it with `attr_check_append()` function.
  17  *
  18  * - Call `git_check_attr()` to check the attributes for the path.
  19  *
  20  * - Inspect `attr_check` structure to see how each of the attribute in the
  21  *   array is defined for the path.
  22  *
  23  *
  24  * Example
  25  * -------
  26  *
  27  * To see how attributes "crlf" and "ident" are set for different paths.
  28  *
  29  * - Prepare a `struct attr_check` with two elements (because we are checking
  30  *   two attributes):
  31  *
  32  * ------------
  33  * static struct attr_check *check;
  34  * static void setup_check(void)
  35  * {
  36  *      if (check)
  37  *              return; // already done
  38  * check = attr_check_initl("crlf", "ident", NULL);
  39  * }
  40  * ------------
  41  *
  42  * - Call `git_check_attr()` with the prepared `struct attr_check`:
  43  *
  44  * ------------
  45  * const char *path;
  46  *
  47  * setup_check();
  48  * git_check_attr(&the_index, path, check);
  49  * ------------
  50  *
  51  * - Act on `.value` member of the result, left in `check->items[]`:
  52  *
  53  * ------------
  54  * const char *value = check->items[0].value;
  55  *
  56  * if (ATTR_TRUE(value)) {
  57  * The attribute is Set, by listing only the name of the
  58  * attribute in the gitattributes file for the path.
  59  * } else if (ATTR_FALSE(value)) {
  60  * The attribute is Unset, by listing the name of the
  61  *         attribute prefixed with a dash - for the path.
  62  * } else if (ATTR_UNSET(value)) {
  63  * The attribute is neither set nor unset for the path.
  64  * } else if (!strcmp(value, "input")) {
  65  * If none of ATTR_TRUE(), ATTR_FALSE(), or ATTR_UNSET() is
  66  *         true, the value is a string set in the gitattributes
  67  * file for the path by saying "attr=value".
  68  * } else if (... other check using value as string ...) {
  69  * ...
  70  * }
  71  * ------------
  72  *
  73  * To see how attributes in argv[] are set for different paths, only
  74  * the first step in the above would be different.
  75  *
  76  * ------------
  77  * static struct attr_check *check;
  78  * static void setup_check(const char **argv)
  79  * {
  80  *     check = attr_check_alloc();
  81  *     while (*argv) {
  82  *         struct git_attr *attr = git_attr(*argv);
  83  *         attr_check_append(check, attr);
  84  *         argv++;
  85  *     }
  86  * }
  87  * ------------
  88  *
  89  *
  90  * Querying All Attributes
  91  * -----------------------
  92  *
  93  * To get the values of all attributes associated with a file:
  94  *
  95  * - Prepare an empty `attr_check` structure by calling `attr_check_alloc()`.
  96  *
  97  * - Call `git_all_attrs()`, which populates the `attr_check` with the
  98  * attributes attached to the path.
  99  *
 100  * - Iterate over the `attr_check.items[]` array to examine the attribute
 101  * names and values. The name of the attribute described by an
 102  * `attr_check.items[]` object can be retrieved via
 103  * `git_attr_name(check->items[i].attr)`. (Please note that no items will be
 104  * returned for unset attributes, so `ATTR_UNSET()` will return false for all
 105  * returned `attr_check.items[]` objects.)
 106  *
 107  * - Free the `attr_check` struct by calling `attr_check_free()`.
 108  */
 109
 110 /**
 111  * The maximum line length for a gitattributes file. If the line exceeds this
 112  * length we will ignore it.
 113  */
 114 #define ATTR_MAX_LINE_LENGTH 2048
 115
 116  /**
 117   * The maximum size of the giattributes file. If the file exceeds this size we
 118   * will ignore it.
 119   */
 120 #define ATTR_MAX_FILE_SIZE (100 * 1024 * 1024)
 121
 122 struct index_state;
 123
 124 /**
 125  * An attribute is an opaque object that is identified by its name. Pass the
 126  * name to `git_attr()` function to obtain the object of this type.
 127  * The internal representation of this structure is of no interest to the
 128  * calling programs. The name of the attribute can be retrieved by calling
 129  * `git_attr_name()`.
 130  */
 131 struct git_attr;
 132
 133 /* opaque structures used internally for attribute collection */
 134 struct all_attrs_item;
 135 struct attr_stack;
 136
 137 /*
 138  * The textual object name for the tree-ish used by git_check_attr()
 139  * to read attributes from (instead of from the working tree).
 140  */
 141 void set_git_attr_source(const char *);
 142
 143 /*
 144  * Given a string, return the gitattribute object that
 145  * corresponds to it.
 146  */
 147 const struct git_attr *git_attr(const char *);
 148
 149 /* Internal use */
 150 extern const char git_attr__true[];
 151 extern const char git_attr__false[];
 152
 153 /**
 154  * Attribute Values
 155  * ----------------
 156  *
 157  * An attribute for a path can be in one of four states: Set, Unset, Unspecified
 158  * or set to a string, and `.value` member of `struct attr_check_item` records
 159  * it. The three macros check these, if none of them returns true, `.value`
 160  * member points at a string value of the attribute for the path.
 161  */
 162
 163 /* Returns true if the attribute is Set for the path. */
 164 #define ATTR_TRUE(v) ((v) == git_attr__true)
 165
 166 /* Returns true if the attribute is Unset for the path. */
 167 #define ATTR_FALSE(v) ((v) == git_attr__false)
 168
 169 /* Returns true if the attribute is Unspecified for the path. */
 170 #define ATTR_UNSET(v) ((v) == NULL)
 171
 172 /* This structure represents one attribute and its value. */
 173 struct attr_check_item {
 174         const struct git_attr *attr;
 175         const char *value;
 176 };
 177
 178 /**
 179  * This structure represents a collection of `attr_check_item`. It is passed to
 180  * `git_check_attr()` function, specifying the attributes to check, and
 181  * receives their values.
 182  */
 183 struct attr_check {
 184         int nr;
 185         int alloc;
 186         struct attr_check_item *items;
 187         int all_attrs_nr;
 188         struct all_attrs_item *all_attrs;
 189         struct attr_stack *stack;
 190 };
 191
 192 struct attr_check *attr_check_alloc(void);
 193
 194 LAST_ARG_MUST_BE_NULL
 195 struct attr_check *attr_check_initl(const char *, ...);
 196 struct attr_check *attr_check_dup(const struct attr_check *check);
 197
 198 struct attr_check_item *attr_check_append(struct attr_check *check,
 199                                           const struct git_attr *attr);
 200
 201 void attr_check_reset(struct attr_check *check);
 202 void attr_check_clear(struct attr_check *check);
 203 void attr_check_free(struct attr_check *check);
 204
 205 /*
 206  * Return the name of the attribute represented by the argument.  The
 207  * return value is a pointer to a null-delimited string that is part
 208  * of the internal data structure; it should not be modified or freed.
 209  */
 210 const char *git_attr_name(const struct git_attr *);
 211
 212 void git_check_attr(struct index_state *istate,
 213                     const char *path,
 214                     struct attr_check *check);
 215
 216 /*
 217  * Retrieve all attributes that apply to the specified path.
 218  * check holds the attributes and their values.
 219  */
 220 void git_all_attrs(struct index_state *istate,
 221                    const char *path, struct attr_check *check);
 222
 223 enum git_attr_direction {
 224         GIT_ATTR_CHECKIN,
 225         GIT_ATTR_CHECKOUT,
 226         GIT_ATTR_INDEX
 227 };
 228 void git_attr_set_direction(enum git_attr_direction new_direction);
 229
 230 void attr_start(void);
 231
 232 /* Return the system gitattributes file. */
 233 const char *git_attr_system_file(void);
 234
 235 /* Return the global gitattributes file, if any. */
 236 const char *git_attr_global_file(void);
 237
 238 /* Return whether the system gitattributes file is enabled and should be used. */
 239 int git_attr_system_is_enabled(void);
 240
 241 extern char *git_attr_tree;
 242
 243 #endif /* ATTR_H */