diff options
Diffstat (limited to 'include/git2/tag.h')
| -rw-r--r-- | include/git2/tag.h | 141 |
1 files changed, 85 insertions, 56 deletions
diff --git a/include/git2/tag.h b/include/git2/tag.h index 859c28995..84c954c27 100644 --- a/include/git2/tag.h +++ b/include/git2/tag.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2009-2012 the libgit2 contributors + * Copyright (C) the libgit2 contributors. All rights reserved. * * This file is part of libgit2, distributed under the GNU GPL v2 with * a Linking Exception. For full terms see the included COPYING file. @@ -11,6 +11,7 @@ #include "types.h" #include "oid.h" #include "object.h" +#include "strarray.h" /** * @file git2/tag.h @@ -24,14 +25,16 @@ GIT_BEGIN_DECL /** * Lookup a tag object from the repository. * - * @param tag pointer to the looked up tag + * @param out pointer to the looked up tag * @param repo the repo to use when locating the tag. * @param id identity of the tag to locate. * @return 0 or an error code */ -GIT_INLINE(int) git_tag_lookup(git_tag **tag, git_repository *repo, const git_oid *id) +GIT_INLINE(int) git_tag_lookup( + git_tag **out, git_repository *repo, const git_oid *id) { - return git_object_lookup((git_object **)tag, repo, id, (git_otype)GIT_OBJ_TAG); + return git_object_lookup( + (git_object **)out, repo, id, (git_otype)GIT_OBJ_TAG); } /** @@ -40,32 +43,33 @@ GIT_INLINE(int) git_tag_lookup(git_tag **tag, git_repository *repo, const git_oi * * @see git_object_lookup_prefix * - * @param tag pointer to the looked up tag + * @param out pointer to the looked up tag * @param repo the repo to use when locating the tag. * @param id identity of the tag to locate. * @param len the length of the short identifier * @return 0 or an error code */ -GIT_INLINE(int) git_tag_lookup_prefix(git_tag **tag, git_repository *repo, const git_oid *id, unsigned int len) +GIT_INLINE(int) git_tag_lookup_prefix( + git_tag **out, git_repository *repo, const git_oid *id, size_t len) { - return git_object_lookup_prefix((git_object **)tag, repo, id, len, (git_otype)GIT_OBJ_TAG); + return git_object_lookup_prefix( + (git_object **)out, repo, id, len, (git_otype)GIT_OBJ_TAG); } /** * Close an open tag * - * This is a wrapper around git_object_free() + * You can no longer use the git_tag pointer after this call. * - * IMPORTANT: - * It *is* necessary to call this method when you stop - * using a tag. Failure to do so will cause a memory leak. + * IMPORTANT: You MUST call this method when you are through with a tag to + * release memory. Failure to do so will cause a memory leak. * * @param tag the tag to close */ GIT_INLINE(void) git_tag_free(git_tag *tag) { - git_object_free((git_object *) tag); + git_object_free((git_object *)tag); } @@ -75,7 +79,7 @@ GIT_INLINE(void) git_tag_free(git_tag *tag) * @param tag a previously loaded tag. * @return object identity for the tag. */ -GIT_EXTERN(const git_oid *) git_tag_id(git_tag *tag); +GIT_EXTERN(const git_oid *) git_tag_id(const git_tag *tag); /** * Get the tagged object of a tag @@ -83,11 +87,11 @@ GIT_EXTERN(const git_oid *) git_tag_id(git_tag *tag); * This method performs a repository lookup for the * given object and returns it * - * @param target pointer where to store the target + * @param target_out pointer where to store the target * @param tag a previously loaded tag. * @return 0 or an error code */ -GIT_EXTERN(int) git_tag_target(git_object **target, git_tag *tag); +GIT_EXTERN(int) git_tag_target(git_object **target_out, const git_tag *tag); /** * Get the OID of the tagged object of a tag @@ -95,7 +99,7 @@ GIT_EXTERN(int) git_tag_target(git_object **target, git_tag *tag); * @param tag a previously loaded tag. * @return pointer to the OID */ -GIT_EXTERN(const git_oid *) git_tag_target_oid(git_tag *tag); +GIT_EXTERN(const git_oid *) git_tag_target_id(const git_tag *tag); /** * Get the type of a tag's tagged object @@ -103,7 +107,7 @@ GIT_EXTERN(const git_oid *) git_tag_target_oid(git_tag *tag); * @param tag a previously loaded tag. * @return type of the tagged object */ -GIT_EXTERN(git_otype) git_tag_type(git_tag *tag); +GIT_EXTERN(git_otype) git_tag_target_type(const git_tag *tag); /** * Get the name of a tag @@ -111,23 +115,23 @@ GIT_EXTERN(git_otype) git_tag_type(git_tag *tag); * @param tag a previously loaded tag. * @return name of the tag */ -GIT_EXTERN(const char *) git_tag_name(git_tag *tag); +GIT_EXTERN(const char *) git_tag_name(const git_tag *tag); /** * Get the tagger (author) of a tag * * @param tag a previously loaded tag. - * @return reference to the tag's author + * @return reference to the tag's author or NULL when unspecified */ -GIT_EXTERN(const git_signature *) git_tag_tagger(git_tag *tag); +GIT_EXTERN(const git_signature *) git_tag_tagger(const git_tag *tag); /** * Get the message of a tag * * @param tag a previously loaded tag. - * @return message of the tag + * @return message of the tag or NULL when unspecified */ -GIT_EXTERN(const char *) git_tag_message(git_tag *tag); +GIT_EXTERN(const char *) git_tag_message(const git_tag *tag); /** @@ -137,8 +141,12 @@ GIT_EXTERN(const char *) git_tag_message(git_tag *tag); * this tag object. If `force` is true and a reference * already exists with the given name, it'll be replaced. * - * The message will be cleaned up from excess whitespace - * it will be made sure that the last line ends with a '\n'. + * The message will not be cleaned up. This can be achieved + * through `git_message_prettify()`. + * + * The tag name will be checked for validity. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. * * @param oid Pointer where to store the OID of the * newly created tag. If the tag already exists, this parameter @@ -161,18 +169,18 @@ GIT_EXTERN(const char *) git_tag_message(git_tag *tag); * * @param force Overwrite existing references * - * @return 0 or an error code + * @return 0 on success, GIT_EINVALIDSPEC or an error code * A tag object is written to the ODB, and a proper reference * is written in the /refs/tags folder, pointing to it */ GIT_EXTERN(int) git_tag_create( - git_oid *oid, - git_repository *repo, - const char *tag_name, - const git_object *target, - const git_signature *tagger, - const char *message, - int force); + git_oid *oid, + git_repository *repo, + const char *tag_name, + const git_object *target, + const git_signature *tagger, + const char *message, + int force); /** * Create a new tag in the repository from a buffer @@ -181,13 +189,13 @@ GIT_EXTERN(int) git_tag_create( * @param repo Repository where to store the tag * @param buffer Raw tag data * @param force Overwrite existing tags - * @return 0 on sucess; error code otherwise + * @return 0 on success; error code otherwise */ GIT_EXTERN(int) git_tag_create_frombuffer( - git_oid *oid, - git_repository *repo, - const char *buffer, - int force); + git_oid *oid, + git_repository *repo, + const char *buffer, + int force); /** * Create a new lightweight tag pointing at a target object @@ -196,6 +204,9 @@ GIT_EXTERN(int) git_tag_create_frombuffer( * this target object. If `force` is true and a reference * already exists with the given name, it'll be replaced. * + * The tag name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param oid Pointer where to store the OID of the provided * target object. If the tag already exists, this parameter * will be filled with the oid of the existing pointed object @@ -212,30 +223,33 @@ GIT_EXTERN(int) git_tag_create_frombuffer( * * @param force Overwrite existing references * - * @return 0 or an error code + * @return 0 on success, GIT_EINVALIDSPEC or an error code * A proper reference is written in the /refs/tags folder, * pointing to the provided target object */ GIT_EXTERN(int) git_tag_create_lightweight( - git_oid *oid, - git_repository *repo, - const char *tag_name, - const git_object *target, - int force); + git_oid *oid, + git_repository *repo, + const char *tag_name, + const git_object *target, + int force); /** * Delete an existing tag reference. * + * The tag name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param repo Repository where lives the tag * * @param tag_name Name of the tag to be deleted; * this name is validated for consistency. * - * @return 0 or an error code + * @return 0 on success, GIT_EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_tag_delete( - git_repository *repo, - const char *tag_name); + git_repository *repo, + const char *tag_name); /** * Fill a list with all the tags in the Repository @@ -251,8 +265,8 @@ GIT_EXTERN(int) git_tag_delete( * @return 0 or an error code */ GIT_EXTERN(int) git_tag_list( - git_strarray *tag_names, - git_repository *repo); + git_strarray *tag_names, + git_repository *repo); /** * Fill a list with all the tags in the Repository @@ -273,24 +287,39 @@ GIT_EXTERN(int) git_tag_list( * @return 0 or an error code */ GIT_EXTERN(int) git_tag_list_match( - git_strarray *tag_names, - const char *pattern, - git_repository *repo); + git_strarray *tag_names, + const char *pattern, + git_repository *repo); + + +typedef int (*git_tag_foreach_cb)(const char *name, git_oid *oid, void *payload); + +/** + * Call callback `cb' for each tag in the repository + * + * @param repo Repository + * @param callback Callback function + * @param payload Pointer to callback data (optional) + */ +GIT_EXTERN(int) git_tag_foreach( + git_repository *repo, + git_tag_foreach_cb callback, + void *payload); + /** - * Recursively peel a tag until a non tag git_object - * is met + * Recursively peel a tag until a non tag git_object is found * * The retrieved `tag_target` object is owned by the repository * and should be closed with the `git_object_free` method. * - * @param tag_target Pointer to the peeled git_object + * @param tag_target_out Pointer to the peeled git_object * @param tag The tag to be processed * @return 0 or an error code */ GIT_EXTERN(int) git_tag_peel( - git_object **tag_target, - git_tag *tag); + git_object **tag_target_out, + const git_tag *tag); /** @} */ GIT_END_DECL |