include/git2/tag.h

   1 /*
   2  * This file is free software; you can redistribute it and/or modify
   3  * it under the terms of the GNU General Public License, version 2,
   4  * as published by the Free Software Foundation.
   5  *
   6  * In addition to the permissions in the GNU General Public License,
   7  * the authors give you unlimited permission to link the compiled
   8  * version of this file into combinations with other programs,
   9  * and to distribute those combinations without any restriction
  10  * coming from the use of this file.  (The General Public License
  11  * restrictions do apply in other respects; for example, they cover
  12  * modification of the file, and distribution when not linked into
  13  * a combined executable.)
  14  *
  15  * This file is distributed in the hope that it will be useful, but
  16  * WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; see the file COPYING.  If not, write to
  22  * the Free Software Foundation, 51 Franklin Street, Fifth Floor,
  23  * Boston, MA 02110-1301, USA.
  24  */
  25 #ifndef INCLUDE_git_tag_h__
  26 #define INCLUDE_git_tag_h__
  27
  28 #include "common.h"
  29 #include "types.h"
  30 #include "oid.h"
  31 #include "object.h"
  32
  33 /**
  34  * @file git2/tag.h
  35  * @brief Git tag parsing routines
  36  * @defgroup git_tag Git tag management
  37  * @ingroup Git
  38  * @{
  39  */
  40 GIT_BEGIN_DECL
  41
  42 /**
  43  * Lookup a tag object from the repository.
  44  *
  45  * @param tag pointer to the looked up tag
  46  * @param repo the repo to use when locating the tag.
  47  * @param id identity of the tag to locate.
  48  * @return 0 on success; error code otherwise
  49  */
  50 GIT_INLINE(int) git_tag_lookup(git_tag **tag, git_repository *repo, const git_oid *id)
  51 {
  52         return git_object_lookup((git_object **)tag, repo, id, (git_otype)GIT_OBJ_TAG);
  53 }
  54
  55 /**
  56  * Lookup a tag object from the repository,
  57  * given a prefix of its identifier (short id).
  58  *
  59  * @see git_object_lookup_prefix
  60  *
  61  * @param tag pointer to the looked up tag
  62  * @param repo the repo to use when locating the tag.
  63  * @param id identity of the tag to locate.
  64  * @param len the length of the short identifier
  65  * @return 0 on success; error code otherwise
  66  */
  67 GIT_INLINE(int) git_tag_lookup_prefix(git_tag **tag, git_repository *repo, const git_oid *id, unsigned int len)
  68 {
  69         return git_object_lookup_prefix((git_object **)tag, repo, id, len, (git_otype)GIT_OBJ_TAG);
  70 }
  71
  72 /**
  73  * Close an open tag
  74  *
  75  * This is a wrapper around git_object_close()
  76  *
  77  * IMPORTANT:
  78  * It *is* necessary to call this method when you stop
  79  * using a tag. Failure to do so will cause a memory leak.
  80  *
  81  * @param tag the tag to close
  82  */
  83
  84 GIT_INLINE(void) git_tag_close(git_tag *tag)
  85 {
  86         git_object_close((git_object *) tag);
  87 }
  88
  89
  90 /**
  91  * Get the id of a tag.
  92  *
  93  * @param tag a previously loaded tag.
  94  * @return object identity for the tag.
  95  */
  96 GIT_EXTERN(const git_oid *) git_tag_id(git_tag *tag);
  97
  98 /**
  99  * Get the tagged object of a tag
 100  *
 101  * This method performs a repository lookup for the
 102  * given object and returns it
 103  *
 104  * @param target pointer where to store the target
 105  * @param tag a previously loaded tag.
 106  * @return 0 on success; error code otherwise
 107  */
 108 GIT_EXTERN(int) git_tag_target(git_object **target, git_tag *t);
 109
 110 /**
 111  * Get the OID of the tagged object of a tag
 112  *
 113  * @param tag a previously loaded tag.
 114  * @return pointer to the OID
 115  */
 116 GIT_EXTERN(const git_oid *) git_tag_target_oid(git_tag *t);
 117
 118 /**
 119  * Get the type of a tag's tagged object
 120  *
 121  * @param tag a previously loaded tag.
 122  * @return type of the tagged object
 123  */
 124 GIT_EXTERN(git_otype) git_tag_type(git_tag *t);
 125
 126 /**
 127  * Get the name of a tag
 128  *
 129  * @param tag a previously loaded tag.
 130  * @return name of the tag
 131  */
 132 GIT_EXTERN(const char *) git_tag_name(git_tag *t);
 133
 134 /**
 135  * Get the tagger (author) of a tag
 136  *
 137  * @param tag a previously loaded tag.
 138  * @return reference to the tag's author
 139  */
 140 GIT_EXTERN(const git_signature *) git_tag_tagger(git_tag *t);
 141
 142 /**
 143  * Get the message of a tag
 144  *
 145  * @param tag a previously loaded tag.
 146  * @return message of the tag
 147  */
 148 GIT_EXTERN(const char *) git_tag_message(git_tag *t);
 149
 150
 151 /**
 152  * Create a new tag in the repository from an OID
 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 existed tag, and the function will
 157  * return a 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 OID to which this tag points; note that no
 166  *      validation is done on this OID. Use the _o version of this
 167  *      method to assure a proper object is being tagged
 168  *
 169  * @param target_type Type of the tagged OID; note that no
 170  *      validation is performed here either
 171  *
 172  * @param tagger Signature of the tagger for this tag, and
 173  *  of the tagging time
 174  *
 175  * @param message Full message for this tag
 176  *
 177  * @return 0 on success; error code otherwise.
 178  *      A tag object is written to the ODB, and a proper reference
 179  *      is written in the /refs/tags folder, pointing to it
 180  */
 181 GIT_EXTERN(int) git_tag_create(
 182                 git_oid *oid,
 183                 git_repository *repo,
 184                 const char *tag_name,
 185                 const git_oid *target,
 186                 git_otype target_type,
 187                 const git_signature *tagger,
 188                 const char *message);
 189
 190
 191 /**
 192  * Create a new tag in the repository from an existing
 193  * `git_object` instance
 194  *
 195  * This method replaces the `target` and `target_type`
 196  * paremeters of `git_tag_create` by a single instance
 197  * of a `const git_object *`, which is assured to be
 198  * a proper object in the ODB and hence will create
 199  * a valid tag
 200  *
 201  * @see git_tag_create
 202  */
 203 GIT_EXTERN(int) git_tag_create_o(
 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  *
 216  * @param repo Repository where to store the tag
 217  *
 218  * @param buffer Raw tag data
 219  */
 220 GIT_EXTERN(int) git_tag_create_frombuffer(
 221                 git_oid *oid,
 222                 git_repository *repo,
 223                 const char *buffer);
 224
 225 /**
 226  * Create a new tag in the repository from an OID
 227  * and overwrite an already existing tag reference, if any.
 228  *
 229  * @param oid Pointer where to store the OID of the
 230  *      newly created tag
 231  *
 232  * @param repo Repository where to store the tag
 233  *
 234  * @param tag_name Name for the tag; this name is validated
 235  * for consistency.
 236  *
 237  * @param target OID to which this tag points; note that no
 238  *      validation is done on this OID. Use the _fo version of this
 239  *      method to assure a proper object is being tagged
 240  *
 241  * @param target_type Type of the tagged OID; note that no
 242  *      validation is performed here either
 243  *
 244  * @param tagger Signature of the tagger for this tag, and
 245  *  of the tagging time
 246  *
 247  * @param message Full message for this tag
 248  *
 249  * @return 0 on success; error code otherwise.
 250  *      A tag object is written to the ODB, and a proper reference
 251  *      is written in the /refs/tags folder, pointing to it
 252  */
 253 GIT_EXTERN(int) git_tag_create_f(
 254                 git_oid *oid,
 255                 git_repository *repo,
 256                 const char *tag_name,
 257                 const git_oid *target,
 258                 git_otype target_type,
 259                 const git_signature *tagger,
 260                 const char *message);
 261
 262 /**
 263  * Create a new tag in the repository from an existing
 264  * `git_object` instance and overwrite an already existing
 265  * tag reference, if any.
 266  *
 267  * This method replaces the `target` and `target_type`
 268  * paremeters of `git_tag_create_f` by a single instance
 269  * of a `const git_object *`, which is assured to be
 270  * a proper object in the ODB and hence will create
 271  * a valid tag
 272  *
 273  * @see git_tag_create_f
 274  */
 275 GIT_EXTERN(int) git_tag_create_fo(
 276                 git_oid *oid,
 277                 git_repository *repo,
 278                 const char *tag_name,
 279                 const git_object *target,
 280                 const git_signature *tagger,
 281                 const char *message);
 282
 283 /**
 284  * Delete an existing tag reference.
 285  *
 286  * @param repo Repository where lives the tag
 287  *
 288  * @param tag_name Name of the tag to be deleted;
 289  * this name is validated for consistency.
 290  *
 291  * @return 0 on success; error code otherwise.
 292  */
 293 GIT_EXTERN(int) git_tag_delete(
 294                 git_repository *repo,
 295                 const char *tag_name);
 296
 297 /**
 298  * Fill a list with all the tags in the Repository
 299  *
 300  * The string array will be filled with the names of the
 301  * matching tags; these values are owned by the user and
 302  * should be free'd manually when no longer needed, using
 303  * `git_strarray_free`.
 304  *
 305  * @param array Pointer to a git_strarray structure where
 306  *              the tag names will be stored
 307  * @param repo Repository where to find the tags
 308  * @return 0 on success; error code otherwise
 309  */
 310 GIT_EXTERN(int) git_tag_list(
 311                 git_strarray *tag_names,
 312                 git_repository *repo);
 313
 314 /** @} */
 315 GIT_END_DECL
 316 #endif