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