Junio C Hamano | d0bfd02 | 2007-04-12 01:07:32 -0700 | [diff] [blame] | 1 | #ifndef ATTR_H |
| 2 | #define ATTR_H |
| 3 | |
Heba Waly | 3a1b341 | 2019-11-17 21:04:47 +0000 | [diff] [blame] | 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(); |
John Cai | 44451a2 | 2023-05-06 04:15:29 +0000 | [diff] [blame] | 48 | * git_check_attr(&the_index, path, check); |
Heba Waly | 3a1b341 | 2019-11-17 21:04:47 +0000 | [diff] [blame] | 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 | |
Patrick Steinhardt | dfa6b32 | 2022-12-01 15:45:48 +0100 | [diff] [blame] | 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 | |
Patrick Steinhardt | 3c50032 | 2022-12-01 15:45:53 +0100 | [diff] [blame] | 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 | |
Nguyễn Thái Ngọc Duy | 7a400a2 | 2018-08-13 18:14:20 +0200 | [diff] [blame] | 122 | struct index_state; |
| 123 | |
Heba Waly | 3a1b341 | 2019-11-17 21:04:47 +0000 | [diff] [blame] | 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 | */ |
Junio C Hamano | d0bfd02 | 2007-04-12 01:07:32 -0700 | [diff] [blame] | 131 | struct git_attr; |
| 132 | |
Brandon Williams | dc81cf3 | 2017-01-27 18:02:05 -0800 | [diff] [blame] | 133 | /* opaque structures used internally for attribute collection */ |
Brandon Williams | 685b292 | 2017-01-27 18:02:02 -0800 | [diff] [blame] | 134 | struct all_attrs_item; |
Brandon Williams | dc81cf3 | 2017-01-27 18:02:05 -0800 | [diff] [blame] | 135 | struct attr_stack; |
Brandon Williams | 685b292 | 2017-01-27 18:02:02 -0800 | [diff] [blame] | 136 | |
Junio C Hamano | a5e92ab | 2007-04-18 16:16:37 -0700 | [diff] [blame] | 137 | /* |
John Cai | 44451a2 | 2023-05-06 04:15:29 +0000 | [diff] [blame] | 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 | /* |
Junio C Hamano | a5e92ab | 2007-04-18 16:16:37 -0700 | [diff] [blame] | 144 | * Given a string, return the gitattribute object that |
| 145 | * corresponds to it. |
| 146 | */ |
Brandon Williams | e810e06 | 2017-01-27 18:02:04 -0800 | [diff] [blame] | 147 | const struct git_attr *git_attr(const char *); |
Junio C Hamano | d0bfd02 | 2007-04-12 01:07:32 -0700 | [diff] [blame] | 148 | |
Junio C Hamano | 515106f | 2007-04-16 21:33:31 -0700 | [diff] [blame] | 149 | /* Internal use */ |
Junio C Hamano | a5e92ab | 2007-04-18 16:16:37 -0700 | [diff] [blame] | 150 | extern const char git_attr__true[]; |
| 151 | extern const char git_attr__false[]; |
Junio C Hamano | 515106f | 2007-04-16 21:33:31 -0700 | [diff] [blame] | 152 | |
Heba Waly | 3a1b341 | 2019-11-17 21:04:47 +0000 | [diff] [blame] | 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. */ |
Junio C Hamano | a5e92ab | 2007-04-18 16:16:37 -0700 | [diff] [blame] | 164 | #define ATTR_TRUE(v) ((v) == git_attr__true) |
Heba Waly | 3a1b341 | 2019-11-17 21:04:47 +0000 | [diff] [blame] | 165 | |
| 166 | /* Returns true if the attribute is Unset for the path. */ |
Junio C Hamano | a5e92ab | 2007-04-18 16:16:37 -0700 | [diff] [blame] | 167 | #define ATTR_FALSE(v) ((v) == git_attr__false) |
Heba Waly | 3a1b341 | 2019-11-17 21:04:47 +0000 | [diff] [blame] | 168 | |
| 169 | /* Returns true if the attribute is Unspecified for the path. */ |
Junio C Hamano | a5e92ab | 2007-04-18 16:16:37 -0700 | [diff] [blame] | 170 | #define ATTR_UNSET(v) ((v) == NULL) |
Junio C Hamano | 515106f | 2007-04-16 21:33:31 -0700 | [diff] [blame] | 171 | |
Heba Waly | 3a1b341 | 2019-11-17 21:04:47 +0000 | [diff] [blame] | 172 | /* This structure represents one attribute and its value. */ |
Junio C Hamano | 7bd1805 | 2017-01-27 18:01:54 -0800 | [diff] [blame] | 173 | struct attr_check_item { |
Junio C Hamano | ec4d77a | 2017-01-27 18:01:48 -0800 | [diff] [blame] | 174 | const struct git_attr *attr; |
Junio C Hamano | a5e92ab | 2007-04-18 16:16:37 -0700 | [diff] [blame] | 175 | const char *value; |
Junio C Hamano | d0bfd02 | 2007-04-12 01:07:32 -0700 | [diff] [blame] | 176 | }; |
| 177 | |
Heba Waly | 3a1b341 | 2019-11-17 21:04:47 +0000 | [diff] [blame] | 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 | */ |
Junio C Hamano | 3729376 | 2017-01-30 10:05:20 -0800 | [diff] [blame] | 183 | struct attr_check { |
| 184 | int nr; |
| 185 | int alloc; |
| 186 | struct attr_check_item *items; |
Brandon Williams | 685b292 | 2017-01-27 18:02:02 -0800 | [diff] [blame] | 187 | int all_attrs_nr; |
| 188 | struct all_attrs_item *all_attrs; |
Brandon Williams | dc81cf3 | 2017-01-27 18:02:05 -0800 | [diff] [blame] | 189 | struct attr_stack *stack; |
Junio C Hamano | 3729376 | 2017-01-30 10:05:20 -0800 | [diff] [blame] | 190 | }; |
| 191 | |
Nguyễn Thái Ngọc Duy | c30f2e2 | 2018-06-30 11:20:21 +0200 | [diff] [blame] | 192 | struct attr_check *attr_check_alloc(void); |
Junio C Hamano | ba74464 | 2024-06-08 11:37:46 -0700 | [diff] [blame] | 193 | |
| 194 | LAST_ARG_MUST_BE_NULL |
Nguyễn Thái Ngọc Duy | c30f2e2 | 2018-06-30 11:20:21 +0200 | [diff] [blame] | 195 | struct attr_check *attr_check_initl(const char *, ...); |
| 196 | struct attr_check *attr_check_dup(const struct attr_check *check); |
Junio C Hamano | 3729376 | 2017-01-30 10:05:20 -0800 | [diff] [blame] | 197 | |
Nguyễn Thái Ngọc Duy | c30f2e2 | 2018-06-30 11:20:21 +0200 | [diff] [blame] | 198 | struct attr_check_item *attr_check_append(struct attr_check *check, |
| 199 | const struct git_attr *attr); |
Junio C Hamano | 3729376 | 2017-01-30 10:05:20 -0800 | [diff] [blame] | 200 | |
Nguyễn Thái Ngọc Duy | c30f2e2 | 2018-06-30 11:20:21 +0200 | [diff] [blame] | 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); |
Junio C Hamano | 3729376 | 2017-01-30 10:05:20 -0800 | [diff] [blame] | 204 | |
Michael Haggerty | 352404a | 2011-08-04 06:36:17 +0200 | [diff] [blame] | 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 | */ |
Nguyễn Thái Ngọc Duy | c30f2e2 | 2018-06-30 11:20:21 +0200 | [diff] [blame] | 210 | const char *git_attr_name(const struct git_attr *); |
Michael Haggerty | 352404a | 2011-08-04 06:36:17 +0200 | [diff] [blame] | 211 | |
Derrick Stolee | 847a9e5 | 2021-04-01 01:49:39 +0000 | [diff] [blame] | 212 | void git_check_attr(struct index_state *istate, |
John Cai | 44451a2 | 2023-05-06 04:15:29 +0000 | [diff] [blame] | 213 | const char *path, |
Karthik Nayak | 47cfc9b | 2023-01-14 09:30:38 +0100 | [diff] [blame] | 214 | struct attr_check *check); |
Junio C Hamano | d0bfd02 | 2007-04-12 01:07:32 -0700 | [diff] [blame] | 215 | |
Michael Haggerty | ee548df | 2011-08-04 06:36:23 +0200 | [diff] [blame] | 216 | /* |
Junio C Hamano | 7f86411 | 2017-01-30 10:06:08 -0800 | [diff] [blame] | 217 | * Retrieve all attributes that apply to the specified path. |
| 218 | * check holds the attributes and their values. |
Michael Haggerty | ee548df | 2011-08-04 06:36:23 +0200 | [diff] [blame] | 219 | */ |
John Cai | 44451a2 | 2023-05-06 04:15:29 +0000 | [diff] [blame] | 220 | void git_all_attrs(struct index_state *istate, |
Nguyễn Thái Ngọc Duy | 7a400a2 | 2018-08-13 18:14:20 +0200 | [diff] [blame] | 221 | const char *path, struct attr_check *check); |
Michael Haggerty | ee548df | 2011-08-04 06:36:23 +0200 | [diff] [blame] | 222 | |
Junio C Hamano | 06f33c1 | 2009-03-13 21:24:08 -0700 | [diff] [blame] | 223 | enum git_attr_direction { |
| 224 | GIT_ATTR_CHECKIN, |
Nguyễn Thái Ngọc Duy | 4191e80 | 2009-04-18 00:17:58 +0200 | [diff] [blame] | 225 | GIT_ATTR_CHECKOUT, |
Gary V. Vaughan | 4b05548 | 2010-05-14 09:31:35 +0000 | [diff] [blame] | 226 | GIT_ATTR_INDEX |
Junio C Hamano | 06f33c1 | 2009-03-13 21:24:08 -0700 | [diff] [blame] | 227 | }; |
Nguyễn Thái Ngọc Duy | c4500e2 | 2018-08-13 18:14:33 +0200 | [diff] [blame] | 228 | void git_attr_set_direction(enum git_attr_direction new_direction); |
Junio C Hamano | 06f33c1 | 2009-03-13 21:24:08 -0700 | [diff] [blame] | 229 | |
Nguyễn Thái Ngọc Duy | c30f2e2 | 2018-06-30 11:20:21 +0200 | [diff] [blame] | 230 | void attr_start(void); |
Brandon Williams | 1a600b7 | 2017-01-27 18:02:01 -0800 | [diff] [blame] | 231 | |
brian m. carlson | 15780bb | 2023-06-27 16:19:00 +0000 | [diff] [blame] | 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 | |
John Cai | 9f9c40c | 2023-10-13 17:39:30 +0000 | [diff] [blame] | 241 | extern const char *git_attr_tree; |
| 242 | |
Junio C Hamano | d0bfd02 | 2007-04-12 01:07:32 -0700 | [diff] [blame] | 243 | #endif /* ATTR_H */ |