about summary refs log tree commit diff
path: root/third_party/git/attr.h
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/attr.h')
-rw-r--r--third_party/git/attr.h141
1 files changed, 7 insertions, 134 deletions
diff --git a/third_party/git/attr.h b/third_party/git/attr.h
index 404548f028a8..b0378bfe5fea 100644
--- a/third_party/git/attr.h
+++ b/third_party/git/attr.h
@@ -1,121 +1,9 @@
 #ifndef ATTR_H
 #define ATTR_H
 
-/**
- * gitattributes mechanism gives a uniform way to associate various attributes
- * to set of paths.
- *
- *
- * Querying Specific Attributes
- * ----------------------------
- *
- * - Prepare `struct attr_check` using attr_check_initl() function, enumerating
- *   the names of attributes whose values you are interested in, terminated with
- *   a NULL pointer.  Alternatively, an empty `struct attr_check` can be
- *   prepared by calling `attr_check_alloc()` function and then attributes you
- *   want to ask about can be added to it with `attr_check_append()` function.
- *
- * - Call `git_check_attr()` to check the attributes for the path.
- *
- * - Inspect `attr_check` structure to see how each of the attribute in the
- *   array is defined for the path.
- *
- *
- * Example
- * -------
- *
- * To see how attributes "crlf" and "ident" are set for different paths.
- *
- * - Prepare a `struct attr_check` with two elements (because we are checking
- *   two attributes):
- *
- * ------------
- * static struct attr_check *check;
- * static void setup_check(void)
- * {
- * 	if (check)
- * 		return; // already done
- * check = attr_check_initl("crlf", "ident", NULL);
- * }
- * ------------
- *
- * - Call `git_check_attr()` with the prepared `struct attr_check`:
- *
- * ------------
- * const char *path;
- *
- * setup_check();
- * git_check_attr(path, check);
- * ------------
- *
- * - Act on `.value` member of the result, left in `check->items[]`:
- *
- * ------------
- * const char *value = check->items[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 neither 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 ...) {
- * ...
- * }
- * ------------
- *
- * To see how attributes in argv[] are set for different paths, only
- * the first step in the above would be different.
- *
- * ------------
- * static struct attr_check *check;
- * static void setup_check(const char **argv)
- * {
- *     check = attr_check_alloc();
- *     while (*argv) {
- *         struct git_attr *attr = git_attr(*argv);
- *         attr_check_append(check, attr);
- *         argv++;
- *     }
- * }
- * ------------
- *
- *
- * Querying All Attributes
- * -----------------------
- *
- * To get the values of all attributes associated with a file:
- *
- * - Prepare an empty `attr_check` structure by calling `attr_check_alloc()`.
- *
- * - Call `git_all_attrs()`, which populates the `attr_check` with the
- * attributes attached to the path.
- *
- * - Iterate over the `attr_check.items[]` array to examine the attribute
- * names and values. The name of the attribute described by an
- * `attr_check.items[]` object can be retrieved via
- * `git_attr_name(check->items[i].attr)`. (Please note that no items will be
- * returned for unset attributes, so `ATTR_UNSET()` will return false for all
- * returned `attr_check.items[]` objects.)
- *
- * - Free the `attr_check` struct by calling `attr_check_free()`.
- */
-
 struct index_state;
 
-/**
- * An attribute is an opaque object that is identified by its name. Pass the
- * name 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. The name of the attribute can be retrieved by calling
- * `git_attr_name()`.
- */
+/* An attribute is a pointer to this opaque structure */
 struct git_attr;
 
 /* opaque structures used internally for attribute collection */
@@ -133,36 +21,21 @@ const struct git_attr *git_attr(const char *);
 extern const char git_attr__true[];
 extern const char git_attr__false[];
 
-/**
- * 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 attr_check_item` records
- * it. The three macros check these, if none of them returns true, `.value`
- * member points at a string value of the attribute for the path.
- */
-
-/* Returns true if the attribute is Set for the path. */
+/* For public to check git_attr_check results */
 #define ATTR_TRUE(v) ((v) == git_attr__true)
-
-/* Returns true if the attribute is Unset for the path. */
 #define ATTR_FALSE(v) ((v) == git_attr__false)
-
-/* Returns true if the attribute is Unspecified for the path. */
 #define ATTR_UNSET(v) ((v) == NULL)
 
-/* This structure represents one attribute and its value. */
+/*
+ * Send one or more git_attr_check to git_check_attrs(), and
+ * each 'value' member tells what its value is.
+ * Unset one is returned as NULL.
+ */
 struct attr_check_item {
 	const struct git_attr *attr;
 	const char *value;
 };
 
-/**
- * This structure represents a collection of `attr_check_item`. It is passed to
- * `git_check_attr()` function, specifying the attributes to check, and
- * receives their values.
- */
 struct attr_check {
 	int nr;
 	int alloc;