diff options
Diffstat (limited to 'include/git2/attr.h')
| -rw-r--r-- | include/git2/attr.h | 166 |
1 files changed, 155 insertions, 11 deletions
diff --git a/include/git2/attr.h b/include/git2/attr.h index 81d1e517b..6a05496dc 100644 --- a/include/git2/attr.h +++ b/include/git2/attr.h @@ -19,42 +19,186 @@ */ GIT_BEGIN_DECL +/** + * GIT_ATTR_TRUE checks if an attribute is set on. In core git + * parlance, this the value for "Set" attributes. + * + * For example, if the attribute file contains: + * + * *.c foo + * + * Then for file `xyz.c` looking up attribute "foo" gives a value for + * which `GIT_ATTR_TRUE(value)` is true. + */ #define GIT_ATTR_TRUE(attr) ((attr) == git_attr__true) + +/** + * GIT_ATTR_FALSE checks if an attribute is set off. In core git + * parlance, this is the value for attributes that are "Unset" (not to + * be confused with values that a "Unspecified"). + * + * For example, if the attribute file contains: + * + * *.h -foo + * + * Then for file `zyx.h` looking up attribute "foo" gives a value for + * which `GIT_ATTR_FALSE(value)` is true. + */ #define GIT_ATTR_FALSE(attr) ((attr) == git_attr__false) -#define GIT_ATTR_UNSPECIFIED(attr) ((attr) == NULL) + +/** + * GIT_ATTR_UNSPECIFIED checks if an attribute is unspecified. This + * may be due to the attribute not being mentioned at all or because + * the attribute was explicitly set unspecified via the `!` operator. + * + * For example, if the attribute file contains: + * + * *.c foo + * *.h -foo + * onefile.c !foo + * + * Then for `onefile.c` looking up attribute "foo" yields a value with + * `GIT_ATTR_UNSPECIFIED(value)` of true. Also, looking up "foo" on + * file `onefile.rb` or looking up "bar" on any file will all give + * `GIT_ATTR_UNSPECIFIED(value)` of true. + */ +#define GIT_ATTR_UNSPECIFIED(attr) (!(attr) || (attr) == git_attr__unset) + +/** + * GIT_ATTR_SET_TO_VALUE checks if an attribute is set to a value (as + * opposied to TRUE, FALSE or UNSPECIFIED). This would be the case if + * for a file with something like: + * + * *.txt eol=lf + * + * Given this, looking up "eol" for `onefile.txt` will give back the + * string "lf" and `GIT_ATTR_SET_TO_VALUE(attr)` will return true. + */ +#define GIT_ATTR_SET_TO_VALUE(attr) \ + ((attr) && (attr) != git_attr__unset && \ + (attr) != git_attr__true && (attr) != git_attr__false) GIT_EXTERN(const char *) git_attr__true; GIT_EXTERN(const char *) git_attr__false; +GIT_EXTERN(const char *) git_attr__unset; + +/** + * Check attribute flags: Reading values from index and working directory. + * + * When checking attributes, it is possible to check attribute files + * in both the working directory (if there is one) and the index (if + * there is one). You can explicitly choose where to check and in + * which order using the following flags. + * + * Core git usually checks the working directory then the index, + * except during a checkout when it checks the index first. It will + * use index only for creating archives or for a bare repo (if an + * index has been specified for the bare repo). + */ +#define GIT_ATTR_CHECK_FILE_THEN_INDEX 0 +#define GIT_ATTR_CHECK_INDEX_THEN_FILE 1 +#define GIT_ATTR_CHECK_INDEX_ONLY 2 +/** + * Check attribute flags: Using the system attributes file. + * + * Normally, attribute checks include looking in the /etc (or system + * equivalent) directory for a `gitattributes` file. Passing this + * flag will cause attribute checks to ignore that file. + */ +#define GIT_ATTR_CHECK_NO_SYSTEM (1 << 2) /** - * Lookup attribute for path returning string caller must free + * Look up the value of one git attribute for path. + * + * @param repo The repository containing the path. + * @param flags A combination of GIT_ATTR_CHECK... flags. + * @param path The path to check for attributes. Relative paths are + * interpreted relative to the repo root. The file does + * not have to exist, but if it does not, then it will be + * treated as a plain file (not a directory). + * @param name The name of the attribute to look up. + * @param value Output of the value of the attribute. Use the GIT_ATTR_... + * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just + * use the string value for attributes set to a value. You + * should NOT modify or free this value. */ GIT_EXTERN(int) git_attr_get( - git_repository *repo, const char *path, const char *name, + git_repository *repo, + uint32_t flags, + const char *path, + const char *name, const char **value); /** - * Lookup list of attributes for path, populating array of strings + * Look up a list of git attributes for path. + * + * Use this if you have a known list of attributes that you want to + * look up in a single call. This is somewhat more efficient than + * calling `git_attr_get()` multiple times. + * + * For example, you might write: + * + * const char *attrs[] = { "crlf", "diff", "foo" }; + * const char **values[3]; + * git_attr_get_many(repo, 0, "my/fun/file.c", 3, attrs, values); + * + * Then you could loop through the 3 values to get the settings for + * the three attributes you asked about. + * + * @param repo The repository containing the path. + * @param flags A combination of GIT_ATTR_CHECK... flags. + * @param path The path inside the repo to check attributes. This + * does not have to exist, but if it does not, then + * it will be treated as a plain file (i.e. not a directory). + * @param num_attr The number of attributes being looked up + * @param names An array of num_attr strings containing attribute names. + * @param values An array of num_attr entries that will have string + * pointers written into it for the values of the attributes. + * You should not modify or free the values that are written + * into this array (although of course, you should free the + * array itself if you allocated it). */ GIT_EXTERN(int) git_attr_get_many( - git_repository *repo, const char *path, - size_t num_attr, const char **names, + git_repository *repo, + uint32_t flags, + const char *path, + size_t num_attr, + const char **names, const char **values); /** - * Perform an operation on each attribute of a path. + * Loop over all the git attributes for a path. + * + * @param repo The repository containing the path. + * @param flags A combination of GIT_ATTR_CHECK... flags. + * @param path The path inside the repo to check attributes. This + * does not have to exist, but if it does not, then + * it will be treated as a plain file (i.e. not a directory). + * @param callback The function that will be invoked on each attribute + * and attribute value. The name parameter will be the name + * of the attribute and the value will be the value it is + * set to, including possibly NULL if the attribute is + * explicitly set to UNSPECIFIED using the ! sign. This + * will be invoked only once per attribute name, even if + * there are multiple rules for a given file. The highest + * priority rule will be used. + * @param payload Passed on as extra parameter to callback function. */ GIT_EXTERN(int) git_attr_foreach( - git_repository *repo, const char *path, + git_repository *repo, + uint32_t flags, + const char *path, int (*callback)(const char *name, const char *value, void *payload), void *payload); /** * Flush the gitattributes cache. * - * Call this if you have reason to believe that the attributes files - * on disk no longer match the cached contents of memory. + * Call this if you have reason to believe that the attributes files on + * disk no longer match the cached contents of memory. This will cause + * the attributes files to be reloaded the next time that an attribute + * access function is called. */ GIT_EXTERN(void) git_attr_cache_flush( git_repository *repo); @@ -62,7 +206,7 @@ GIT_EXTERN(void) git_attr_cache_flush( /** * Add a macro definition. * - * Macros will automatically be loaded from the top level .gitattributes + * Macros will automatically be loaded from the top level `.gitattributes` * file of the repository (plus the build-in "binary" macro). This * function allows you to add others. For example, to add the default * macro, you would call: |