1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 module libgit2_d.attr; 8 9 10 private static import libgit2_d.types; 11 12 /** 13 * @file git2/attr.h 14 * @brief Git attribute management routines 15 * @defgroup git_attr Git attribute management routines 16 * @ingroup Git 17 * @{ 18 */ 19 extern (C): 20 nothrow @nogc: 21 public: 22 23 //Linker error 24 version (none) { 25 /** 26 * GIT_ATTR_TRUE checks if an attribute is set on. In core git 27 * parlance, this the value for "Set" attributes. 28 * 29 * For example, if the attribute file contains: 30 * 31 * *.c foo 32 * 33 * Then for file `xyz.c` looking up attribute "foo" gives a value for 34 * which `GIT_ATTR_TRUE(value)` is true. 35 */ 36 pragma(inline, true) 37 nothrow @nogc 38 bool GIT_ATTR_IS_TRUE(const (char)* attr) 39 40 do 41 { 42 return .git_attr_value(attr) == .git_attr_t.GIT_ATTR_VALUE_TRUE; 43 } 44 45 /** 46 * GIT_ATTR_FALSE checks if an attribute is set off. In core git 47 * parlance, this is the value for attributes that are "Unset" (not to 48 * be confused with values that a "Unspecified"). 49 * 50 * For example, if the attribute file contains: 51 * 52 * *.h -foo 53 * 54 * Then for file `zyx.h` looking up attribute "foo" gives a value for 55 * which `GIT_ATTR_FALSE(value)` is true. 56 */ 57 pragma(inline, true) 58 nothrow @nogc 59 bool GIT_ATTR_IS_FALSE(const (char)* attr) 60 61 do 62 { 63 return .git_attr_value(attr) == .git_attr_t.GIT_ATTR_VALUE_FALSE; 64 } 65 66 /** 67 * GIT_ATTR_UNSPECIFIED checks if an attribute is unspecified. This 68 * may be due to the attribute not being mentioned at all or because 69 * the attribute was explicitly set unspecified via the `!` operator. 70 * 71 * For example, if the attribute file contains: 72 * 73 * *.c foo 74 * *.h -foo 75 * onefile.c !foo 76 * 77 * Then for `onefile.c` looking up attribute "foo" yields a value with 78 * `GIT_ATTR_UNSPECIFIED(value)` of true. Also, looking up "foo" on 79 * file `onefile.rb` or looking up "bar" on any file will all give 80 * `GIT_ATTR_UNSPECIFIED(value)` of true. 81 */ 82 pragma(inline, true) 83 nothrow @nogc 84 bool GIT_ATTR_IS_UNSPECIFIED(const (char)* attr) 85 86 do 87 { 88 return .git_attr_value(attr) == .git_attr_t.GIT_ATTR_VALUE_UNSPECIFIED; 89 } 90 91 /** 92 * GIT_ATTR_HAS_VALUE checks if an attribute is set to a value (as 93 * opposed to TRUE, FALSE or UNSPECIFIED). This would be the case if 94 * for a file with something like: 95 * 96 * *.txt eol=lf 97 * 98 * Given this, looking up "eol" for `onefile.txt` will give back the 99 * string "lf" and `GIT_ATTR_SET_TO_VALUE(attr)` will return true. 100 */ 101 pragma(inline, true) 102 nothrow @nogc 103 bool GIT_ATTR_HAS_VALUE(const (char)* attr) 104 105 do 106 { 107 return .git_attr_value(attr) == .git_attr_t.GIT_ATTR_VALUE_STRING; 108 } 109 } 110 111 /** 112 * Possible states for an attribute 113 */ 114 enum git_attr_value_t 115 { 116 /** 117 * The attribute has been left unspecified 118 */ 119 GIT_ATTR_VALUE_UNSPECIFIED = 0, 120 121 /** 122 * The attribute has been set 123 */ 124 GIT_ATTR_VALUE_TRUE, 125 126 /** 127 * The attribute has been unset 128 */ 129 GIT_ATTR_VALUE_FALSE, 130 131 /** 132 * This attribute has a value 133 */ 134 GIT_ATTR_VALUE_STRING, 135 } 136 137 /** 138 * Return the value type for a given attribute. 139 * 140 * This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute 141 * was not set at all), or `VALUE`, if the attribute was set to an 142 * actual string. 143 * 144 * If the attribute has a `VALUE` string, it can be accessed normally 145 * as a null-terminated C string. 146 * 147 * @param attr The attribute 148 * @return the value type for the attribute 149 */ 150 //GIT_EXTERN 151 .git_attr_value_t git_attr_value(const (char)* attr); 152 153 /** 154 * Check attribute flags: Reading values from index and working directory. 155 * 156 * When checking attributes, it is possible to check attribute files 157 * in both the working directory (if there is one) and the index (if 158 * there is one). You can explicitly choose where to check and in 159 * which order using the following flags. 160 * 161 * Core git usually checks the working directory then the index, 162 * except during a checkout when it checks the index first. It will 163 * use index only for creating archives or for a bare repo (if an 164 * index has been specified for the bare repo). 165 */ 166 enum GIT_ATTR_CHECK_FILE_THEN_INDEX = 0; 167 enum GIT_ATTR_CHECK_INDEX_THEN_FILE = 1; 168 enum GIT_ATTR_CHECK_INDEX_ONLY = 2; 169 170 /** 171 * Check attribute flags: controlling extended attribute behavior. 172 * 173 * Normally, attribute checks include looking in the /etc (or system 174 * equivalent) directory for a `gitattributes` file. Passing this 175 * flag will cause attribute checks to ignore that file. 176 * equivalent) directory for a `gitattributes` file. Passing the 177 * `GIT_ATTR_CHECK_NO_SYSTEM` flag will cause attribute checks to 178 * ignore that file. 179 * 180 * Passing the `GIT_ATTR_CHECK_INCLUDE_HEAD` flag will use attributes 181 * from a `.gitattributes` file in the repository at the HEAD revision. 182 */ 183 enum GIT_ATTR_CHECK_NO_SYSTEM = 1 << 2; 184 enum GIT_ATTR_CHECK_INCLUDE_HEAD = 1 << 3; 185 186 /** 187 * Look up the value of one git attribute for path. 188 * 189 * @param value_out Output of the value of the attribute. Use the GIT_ATTR_... 190 * macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just 191 * use the string value for attributes set to a value. You 192 * should NOT modify or free this value. 193 * @param repo The repository containing the path. 194 * @param flags A combination of GIT_ATTR_CHECK... flags. 195 * @param path The path to check for attributes. Relative paths are 196 * interpreted relative to the repo root. The file does 197 * not have to exist, but if it does not, then it will be 198 * treated as a plain file (not a directory). 199 * @param name The name of the attribute to look up. 200 */ 201 //GIT_EXTERN 202 int git_attr_get(const (char)** value_out, libgit2_d.types.git_repository* repo, uint flags, const (char)* path, const (char)* name); 203 204 /** 205 * Look up a list of git attributes for path. 206 * 207 * Use this if you have a known list of attributes that you want to 208 * look up in a single call. This is somewhat more efficient than 209 * calling `git_attr_get()` multiple times. 210 * 211 * For example, you might write: 212 * 213 * const char *attrs[] = { "crlf", "diff", "foo" }; 214 * const char **values[3]; 215 * git_attr_get_many(values, repo, 0, "my/fun/file.c", 3, attrs); 216 * 217 * Then you could loop through the 3 values to get the settings for 218 * the three attributes you asked about. 219 * 220 * @param values_out An array of num_attr entries that will have string 221 * pointers written into it for the values of the attributes. 222 * You should not modify or free the values that are written 223 * into this array (although of course, you should free the 224 * array itself if you allocated it). 225 * @param repo The repository containing the path. 226 * @param flags A combination of GIT_ATTR_CHECK... flags. 227 * @param path The path inside the repo to check attributes. This 228 * does not have to exist, but if it does not, then 229 * it will be treated as a plain file (i.e. not a directory). 230 * @param num_attr The number of attributes being looked up 231 * @param names An array of num_attr strings containing attribute names. 232 */ 233 //GIT_EXTERN 234 int git_attr_get_many(const (char)** values_out, libgit2_d.types.git_repository* repo, uint flags, const (char)* path, size_t num_attr, const (char)** names); 235 236 /** 237 * The callback used with git_attr_foreach. 238 * 239 * This callback will be invoked only once per attribute name, even if there 240 * are multiple rules for a given file. The highest priority rule will be 241 * used. 242 * 243 * @see git_attr_foreach. 244 * 245 * @param name The attribute name. 246 * @param value The attribute value. May be NULL if the attribute is explicitly 247 * set to UNSPECIFIED using the '!' sign. 248 * @param payload A user-specified pointer. 249 * @return 0 to continue looping, non-zero to stop. This value will be returned 250 * from git_attr_foreach. 251 */ 252 alias git_attr_foreach_cb = int function(const (char)* name, const (char)* value, void* payload); 253 254 /** 255 * Loop over all the git attributes for a path. 256 * 257 * @param repo The repository containing the path. 258 * @param flags A combination of GIT_ATTR_CHECK... flags. 259 * @param path Path inside the repo to check attributes. This does not have 260 * to exist, but if it does not, then it will be treated as a 261 * plain file (i.e. not a directory). 262 * @param callback Function to invoke on each attribute name and value. 263 * See git_attr_foreach_cb. 264 * @param payload Passed on as extra parameter to callback function. 265 * @return 0 on success, non-zero callback return value, or error code 266 */ 267 //GIT_EXTERN 268 int git_attr_foreach(libgit2_d.types.git_repository* repo, uint flags, const (char)* path, .git_attr_foreach_cb callback, void* payload); 269 270 /** 271 * Flush the gitattributes cache. 272 * 273 * Call this if you have reason to believe that the attributes files on 274 * disk no longer match the cached contents of memory. This will cause 275 * the attributes files to be reloaded the next time that an attribute 276 * access function is called. 277 * 278 * @param repo The repository containing the gitattributes cache 279 * @return 0 on success, or an error code 280 */ 281 //GIT_EXTERN 282 int git_attr_cache_flush(libgit2_d.types.git_repository* repo); 283 284 /** 285 * Add a macro definition. 286 * 287 * Macros will automatically be loaded from the top level `.gitattributes` 288 * file of the repository (plus the build-in "binary" macro). This 289 * function allows you to add others. For example, to add the default 290 * macro, you would call: 291 * 292 * git_attr_add_macro(repo, "binary", "-diff -crlf"); 293 */ 294 //GIT_EXTERN 295 int git_attr_add_macro(libgit2_d.types.git_repository* repo, const (char)* name, const (char)* values); 296 297 /** @} */