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.tag; 8 9 10 private static import libgit2_d.oid; 11 private static import libgit2_d.strarray; 12 private static import libgit2_d.types; 13 14 /** 15 * @file git2/tag.h 16 * @brief Git tag parsing routines 17 * @defgroup git_tag Git tag management 18 * @ingroup Git 19 * @{ 20 */ 21 extern (C): 22 nothrow @nogc: 23 public: 24 25 /** 26 * Lookup a tag object from the repository. 27 * 28 * @param out_ pointer to the looked up tag 29 * @param repo the repo to use when locating the tag. 30 * @param id identity of the tag to locate. 31 * @return 0 or an error code 32 */ 33 //GIT_EXTERN 34 int git_tag_lookup(libgit2_d.types.git_tag** out_, libgit2_d.types.git_repository* repo, const (libgit2_d.oid.git_oid)* id); 35 36 /** 37 * Lookup a tag object from the repository, 38 * given a prefix of its identifier (short id). 39 * 40 * @see git_object_lookup_prefix 41 * 42 * @param out_ pointer to the looked up tag 43 * @param repo the repo to use when locating the tag. 44 * @param id identity of the tag to locate. 45 * @param len the length of the short identifier 46 * @return 0 or an error code 47 */ 48 //GIT_EXTERN 49 int git_tag_lookup_prefix(libgit2_d.types.git_tag** out_, libgit2_d.types.git_repository* repo, const (libgit2_d.oid.git_oid)* id, size_t len); 50 51 /** 52 * Close an open tag 53 * 54 * You can no longer use the git_tag pointer after this call. 55 * 56 * IMPORTANT: You MUST call this method when you are through with a tag to 57 * release memory. Failure to do so will cause a memory leak. 58 * 59 * @param tag the tag to close 60 */ 61 //GIT_EXTERN 62 void git_tag_free(libgit2_d.types.git_tag* tag); 63 64 /** 65 * Get the id of a tag. 66 * 67 * @param tag a previously loaded tag. 68 * @return object identity for the tag. 69 */ 70 //GIT_EXTERN 71 const (libgit2_d.oid.git_oid)* git_tag_id(const (libgit2_d.types.git_tag)* tag); 72 73 /** 74 * Get the repository that contains the tag. 75 * 76 * @param tag A previously loaded tag. 77 * @return Repository that contains this tag. 78 */ 79 //GIT_EXTERN 80 libgit2_d.types.git_repository* git_tag_owner(const (libgit2_d.types.git_tag)* tag); 81 82 /** 83 * Get the tagged object of a tag 84 * 85 * This method performs a repository lookup for the 86 * given object and returns it 87 * 88 * @param target_out pointer where to store the target 89 * @param tag a previously loaded tag. 90 * @return 0 or an error code 91 */ 92 //GIT_EXTERN 93 int git_tag_target(libgit2_d.types.git_object** target_out, const (libgit2_d.types.git_tag)* tag); 94 95 /** 96 * Get the OID of the tagged object of a tag 97 * 98 * @param tag a previously loaded tag. 99 * @return pointer to the OID 100 */ 101 //GIT_EXTERN 102 const (libgit2_d.oid.git_oid)* git_tag_target_id(const (libgit2_d.types.git_tag)* tag); 103 104 /** 105 * Get the type of a tag's tagged object 106 * 107 * @param tag a previously loaded tag. 108 * @return type of the tagged object 109 */ 110 //GIT_EXTERN 111 libgit2_d.types.git_object_t git_tag_target_type(const (libgit2_d.types.git_tag)* tag); 112 113 /** 114 * Get the name of a tag 115 * 116 * @param tag a previously loaded tag. 117 * @return name of the tag 118 */ 119 //GIT_EXTERN 120 const (char)* git_tag_name(const (libgit2_d.types.git_tag)* tag); 121 122 /** 123 * Get the tagger (author) of a tag 124 * 125 * @param tag a previously loaded tag. 126 * @return reference to the tag's author or null when unspecified 127 */ 128 //GIT_EXTERN 129 const (libgit2_d.types.git_signature)* git_tag_tagger(const (libgit2_d.types.git_tag)* tag); 130 131 /** 132 * Get the message of a tag 133 * 134 * @param tag a previously loaded tag. 135 * @return message of the tag or null when unspecified 136 */ 137 //GIT_EXTERN 138 const (char)* git_tag_message(const (libgit2_d.types.git_tag)* tag); 139 140 /** 141 * Create a new tag in the repository from an object 142 * 143 * A new reference will also be created pointing to 144 * this tag object. If `force` is true and a reference 145 * already exists with the given name, it'll be replaced. 146 * 147 * The message will not be cleaned up. This can be achieved 148 * through `git_message_prettify()`. 149 * 150 * The tag name will be checked for validity. You must avoid 151 * the characters '~', '^', ':', '\\', '?', '[', and '*', and the 152 * sequences ".." and "@{" which have special meaning to revparse. 153 * 154 * @param oid Pointer where to store the OID of the 155 * newly created tag. If the tag already exists, this parameter 156 * will be the oid of the existing tag, and the function will 157 * return a git_error_code.GIT_EEXISTS error code. 158 * 159 * @param repo Repository where to store the tag 160 * 161 * @param tag_name Name for the tag; this name is validated 162 * for consistency. It should also not conflict with an 163 * already existing tag name 164 * 165 * @param target Object to which this tag points. This object 166 * must belong to the given `repo`. 167 * 168 * @param tagger Signature of the tagger for this tag, and 169 * of the tagging time 170 * 171 * @param message Full message for this tag 172 * 173 * @param force Overwrite existing references 174 * 175 * @return 0 on success, git_error_code.GIT_EINVALIDSPEC or an error code 176 * A tag object is written to the ODB, and a proper reference 177 * is written in the /refs/tags folder, pointing to it 178 */ 179 //GIT_EXTERN 180 int git_tag_create(libgit2_d.oid.git_oid* oid, libgit2_d.types.git_repository* repo, const (char)* tag_name, const (libgit2_d.types.git_object)* target, const (libgit2_d.types.git_signature)* tagger, const (char)* message, int force); 181 182 /** 183 * Create a new tag in the object database pointing to a git_object 184 * 185 * The message will not be cleaned up. This can be achieved 186 * through `git_message_prettify()`. 187 * 188 * @param oid Pointer where to store the OID of the 189 * newly created tag 190 * 191 * @param repo Repository where to store the tag 192 * 193 * @param tag_name Name for the tag 194 * 195 * @param target Object to which this tag points. This object 196 * must belong to the given `repo`. 197 * 198 * @param tagger Signature of the tagger for this tag, and 199 * of the tagging time 200 * 201 * @param message Full message for this tag 202 * 203 * @return 0 on success or an error code 204 */ 205 //GIT_EXTERN 206 int git_tag_annotation_create(libgit2_d.oid.git_oid* oid, libgit2_d.types.git_repository* repo, const (char)* tag_name, const (libgit2_d.types.git_object)* target, const (libgit2_d.types.git_signature)* tagger, const (char)* message); 207 208 /** 209 * Create a new tag in the repository from a buffer 210 * 211 * @param oid Pointer where to store the OID of the newly created tag 212 * @param repo Repository where to store the tag 213 * @param buffer Raw tag data 214 * @param force Overwrite existing tags 215 * @return 0 on success; error code otherwise 216 */ 217 //GIT_EXTERN 218 int git_tag_create_from_buffer(libgit2_d.oid.git_oid* oid, libgit2_d.types.git_repository* repo, const (char)* buffer, int force); 219 220 /** 221 * Create a new lightweight tag pointing at a target object 222 * 223 * A new direct reference will be created pointing to 224 * this target object. If `force` is true and a reference 225 * already exists with the given name, it'll be replaced. 226 * 227 * The tag name will be checked for validity. 228 * See `git_tag_create()` for rules about valid names. 229 * 230 * @param oid Pointer where to store the OID of the provided 231 * target object. If the tag already exists, this parameter 232 * will be filled with the oid of the existing pointed object 233 * and the function will return a git_error_code.GIT_EEXISTS error code. 234 * 235 * @param repo Repository where to store the lightweight tag 236 * 237 * @param tag_name Name for the tag; this name is validated 238 * for consistency. It should also not conflict with an 239 * already existing tag name 240 * 241 * @param target Object to which this tag points. This object 242 * must belong to the given `repo`. 243 * 244 * @param force Overwrite existing references 245 * 246 * @return 0 on success, git_error_code.GIT_EINVALIDSPEC or an error code 247 * A proper reference is written in the /refs/tags folder, 248 * pointing to the provided target object 249 */ 250 //GIT_EXTERN 251 int git_tag_create_lightweight(libgit2_d.oid.git_oid* oid, libgit2_d.types.git_repository* repo, const (char)* tag_name, const (libgit2_d.types.git_object)* target, int force); 252 253 /** 254 * Delete an existing tag reference. 255 * 256 * The tag name will be checked for validity. 257 * See `git_tag_create()` for rules about valid names. 258 * 259 * @param repo Repository where lives the tag 260 * 261 * @param tag_name Name of the tag to be deleted; 262 * this name is validated for consistency. 263 * 264 * @return 0 on success, git_error_code.GIT_EINVALIDSPEC or an error code 265 */ 266 //GIT_EXTERN 267 int git_tag_delete(libgit2_d.types.git_repository* repo, const (char)* tag_name); 268 269 /** 270 * Fill a list with all the tags in the Repository 271 * 272 * The string array will be filled with the names of the 273 * matching tags; these values are owned by the user and 274 * should be free'd manually when no longer needed, using 275 * `git_strarray_free`. 276 * 277 * @param tag_names Pointer to a git_strarray structure where 278 * the tag names will be stored 279 * @param repo Repository where to find the tags 280 * @return 0 or an error code 281 */ 282 //GIT_EXTERN 283 int git_tag_list(libgit2_d.strarray.git_strarray* tag_names, libgit2_d.types.git_repository* repo); 284 285 /** 286 * Fill a list with all the tags in the Repository 287 * which name match a defined pattern 288 * 289 * If an empty pattern is provided, all the tags 290 * will be returned. 291 * 292 * The string array will be filled with the names of the 293 * matching tags; these values are owned by the user and 294 * should be free'd manually when no longer needed, using 295 * `git_strarray_free`. 296 * 297 * @param tag_names Pointer to a git_strarray structure where 298 * the tag names will be stored 299 * @param pattern Standard fnmatch pattern 300 * @param repo Repository where to find the tags 301 * @return 0 or an error code 302 */ 303 //GIT_EXTERN 304 int git_tag_list_match(libgit2_d.strarray.git_strarray* tag_names, const (char)* pattern, libgit2_d.types.git_repository* repo); 305 306 /** 307 * Callback used to iterate over tag names 308 * 309 * @see git_tag_foreach 310 * 311 * @param name The tag name 312 * @param oid The tag's OID 313 * @param payload Payload passed to git_tag_foreach 314 * @return non-zero to terminate the iteration 315 */ 316 alias git_tag_foreach_cb = int function(const (char)* name, libgit2_d.oid.git_oid* oid, void* payload); 317 318 /** 319 * Call callback `cb' for each tag in the repository 320 * 321 * @param repo Repository 322 * @param callback Callback function 323 * @param payload Pointer to callback data (optional) 324 */ 325 //GIT_EXTERN 326 int git_tag_foreach(libgit2_d.types.git_repository* repo, .git_tag_foreach_cb callback, void* payload); 327 328 /** 329 * Recursively peel a tag until a non tag git_object is found 330 * 331 * The retrieved `tag_target` object is owned by the repository 332 * and should be closed with the `git_object_free` method. 333 * 334 * @param tag_target_out Pointer to the peeled git_object 335 * @param tag The tag to be processed 336 * @return 0 or an error code 337 */ 338 //GIT_EXTERN 339 int git_tag_peel(libgit2_d.types.git_object** tag_target_out, const (libgit2_d.types.git_tag)* tag); 340 341 /** 342 * Create an in-memory copy of a tag. The copy must be explicitly 343 * free'd or it will leak. 344 * 345 * @param out_ Pointer to store the copy of the tag 346 * @param source Original tag to copy 347 */ 348 //GIT_EXTERN 349 int git_tag_dup(libgit2_d.types.git_tag** out_, libgit2_d.types.git_tag* source); 350 351 /** @} */