blob: afa33ce3be6e96fc77717fd98eed57ee77135def [file] [log] [blame]
Junio C Hamanod0bfd022007-04-12 01:07:32 -07001#ifndef ATTR_H
2#define ATTR_H
3
Heba Waly3a1b3412019-11-17 21:04:47 +00004/**
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 Cai44451a22023-05-06 04:15:29 +000048 * git_check_attr(&the_index, path, check);
Heba Waly3a1b3412019-11-17 21:04:47 +000049 * ------------
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 Steinhardtdfa6b322022-12-01 15:45:48 +0100110/**
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 Steinhardt3c500322022-12-01 15:45:53 +0100116 /**
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 Duy7a400a22018-08-13 18:14:20 +0200122struct index_state;
123
Heba Waly3a1b3412019-11-17 21:04:47 +0000124/**
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 Hamanod0bfd022007-04-12 01:07:32 -0700131struct git_attr;
132
Brandon Williamsdc81cf32017-01-27 18:02:05 -0800133/* opaque structures used internally for attribute collection */
Brandon Williams685b2922017-01-27 18:02:02 -0800134struct all_attrs_item;
Brandon Williamsdc81cf32017-01-27 18:02:05 -0800135struct attr_stack;
Brandon Williams685b2922017-01-27 18:02:02 -0800136
Junio C Hamanoa5e92ab2007-04-18 16:16:37 -0700137/*
John Cai44451a22023-05-06 04:15:29 +0000138 * 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 */
141void set_git_attr_source(const char *);
142
143/*
Junio C Hamanoa5e92ab2007-04-18 16:16:37 -0700144 * Given a string, return the gitattribute object that
145 * corresponds to it.
146 */
Brandon Williamse810e062017-01-27 18:02:04 -0800147const struct git_attr *git_attr(const char *);
Junio C Hamanod0bfd022007-04-12 01:07:32 -0700148
Junio C Hamano515106f2007-04-16 21:33:31 -0700149/* Internal use */
Junio C Hamanoa5e92ab2007-04-18 16:16:37 -0700150extern const char git_attr__true[];
151extern const char git_attr__false[];
Junio C Hamano515106f2007-04-16 21:33:31 -0700152
Heba Waly3a1b3412019-11-17 21:04:47 +0000153/**
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 Hamanoa5e92ab2007-04-18 16:16:37 -0700164#define ATTR_TRUE(v) ((v) == git_attr__true)
Heba Waly3a1b3412019-11-17 21:04:47 +0000165
166/* Returns true if the attribute is Unset for the path. */
Junio C Hamanoa5e92ab2007-04-18 16:16:37 -0700167#define ATTR_FALSE(v) ((v) == git_attr__false)
Heba Waly3a1b3412019-11-17 21:04:47 +0000168
169/* Returns true if the attribute is Unspecified for the path. */
Junio C Hamanoa5e92ab2007-04-18 16:16:37 -0700170#define ATTR_UNSET(v) ((v) == NULL)
Junio C Hamano515106f2007-04-16 21:33:31 -0700171
Heba Waly3a1b3412019-11-17 21:04:47 +0000172/* This structure represents one attribute and its value. */
Junio C Hamano7bd18052017-01-27 18:01:54 -0800173struct attr_check_item {
Junio C Hamanoec4d77a2017-01-27 18:01:48 -0800174 const struct git_attr *attr;
Junio C Hamanoa5e92ab2007-04-18 16:16:37 -0700175 const char *value;
Junio C Hamanod0bfd022007-04-12 01:07:32 -0700176};
177
Heba Waly3a1b3412019-11-17 21:04:47 +0000178/**
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 Hamano37293762017-01-30 10:05:20 -0800183struct attr_check {
184 int nr;
185 int alloc;
186 struct attr_check_item *items;
Brandon Williams685b2922017-01-27 18:02:02 -0800187 int all_attrs_nr;
188 struct all_attrs_item *all_attrs;
Brandon Williamsdc81cf32017-01-27 18:02:05 -0800189 struct attr_stack *stack;
Junio C Hamano37293762017-01-30 10:05:20 -0800190};
191
Nguyễn Thái Ngọc Duyc30f2e22018-06-30 11:20:21 +0200192struct attr_check *attr_check_alloc(void);
Junio C Hamanoba744642024-06-08 11:37:46 -0700193
194LAST_ARG_MUST_BE_NULL
Nguyễn Thái Ngọc Duyc30f2e22018-06-30 11:20:21 +0200195struct attr_check *attr_check_initl(const char *, ...);
196struct attr_check *attr_check_dup(const struct attr_check *check);
Junio C Hamano37293762017-01-30 10:05:20 -0800197
Nguyễn Thái Ngọc Duyc30f2e22018-06-30 11:20:21 +0200198struct attr_check_item *attr_check_append(struct attr_check *check,
199 const struct git_attr *attr);
Junio C Hamano37293762017-01-30 10:05:20 -0800200
Nguyễn Thái Ngọc Duyc30f2e22018-06-30 11:20:21 +0200201void attr_check_reset(struct attr_check *check);
202void attr_check_clear(struct attr_check *check);
203void attr_check_free(struct attr_check *check);
Junio C Hamano37293762017-01-30 10:05:20 -0800204
Michael Haggerty352404a2011-08-04 06:36:17 +0200205/*
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 Duyc30f2e22018-06-30 11:20:21 +0200210const char *git_attr_name(const struct git_attr *);
Michael Haggerty352404a2011-08-04 06:36:17 +0200211
Derrick Stolee847a9e52021-04-01 01:49:39 +0000212void git_check_attr(struct index_state *istate,
John Cai44451a22023-05-06 04:15:29 +0000213 const char *path,
Karthik Nayak47cfc9b2023-01-14 09:30:38 +0100214 struct attr_check *check);
Junio C Hamanod0bfd022007-04-12 01:07:32 -0700215
Michael Haggertyee548df2011-08-04 06:36:23 +0200216/*
Junio C Hamano7f864112017-01-30 10:06:08 -0800217 * Retrieve all attributes that apply to the specified path.
218 * check holds the attributes and their values.
Michael Haggertyee548df2011-08-04 06:36:23 +0200219 */
John Cai44451a22023-05-06 04:15:29 +0000220void git_all_attrs(struct index_state *istate,
Nguyễn Thái Ngọc Duy7a400a22018-08-13 18:14:20 +0200221 const char *path, struct attr_check *check);
Michael Haggertyee548df2011-08-04 06:36:23 +0200222
Junio C Hamano06f33c12009-03-13 21:24:08 -0700223enum git_attr_direction {
224 GIT_ATTR_CHECKIN,
Nguyễn Thái Ngọc Duy4191e802009-04-18 00:17:58 +0200225 GIT_ATTR_CHECKOUT,
Gary V. Vaughan4b055482010-05-14 09:31:35 +0000226 GIT_ATTR_INDEX
Junio C Hamano06f33c12009-03-13 21:24:08 -0700227};
Nguyễn Thái Ngọc Duyc4500e22018-08-13 18:14:33 +0200228void git_attr_set_direction(enum git_attr_direction new_direction);
Junio C Hamano06f33c12009-03-13 21:24:08 -0700229
Nguyễn Thái Ngọc Duyc30f2e22018-06-30 11:20:21 +0200230void attr_start(void);
Brandon Williams1a600b72017-01-27 18:02:01 -0800231
brian m. carlson15780bb2023-06-27 16:19:00 +0000232/* Return the system gitattributes file. */
233const char *git_attr_system_file(void);
234
235/* Return the global gitattributes file, if any. */
236const char *git_attr_global_file(void);
237
238/* Return whether the system gitattributes file is enabled and should be used. */
239int git_attr_system_is_enabled(void);
240
John Cai9f9c40c2023-10-13 17:39:30 +0000241extern const char *git_attr_tree;
242
Junio C Hamanod0bfd022007-04-12 01:07:32 -0700243#endif /* ATTR_H */