2 * Copyright (C) the libgit2 contributors. All rights reserved.
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.
7 #ifndef INCLUDE_git_tag_h__
8 #define INCLUDE_git_tag_h__
18 * @brief Git tag parsing routines
19 * @defgroup git_tag Git tag management
26 * Lookup a tag object from the repository.
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
33 GIT_EXTERN(int) git_tag_lookup(
34 git_tag
**out
, git_repository
*repo
, const git_oid
*id
);
37 * Lookup a tag object from the repository,
38 * given a prefix of its identifier (short id).
40 * @see git_object_lookup_prefix
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
48 GIT_EXTERN(int) git_tag_lookup_prefix(
49 git_tag
**out
, git_repository
*repo
, const git_oid
*id
, size_t len
);
54 * You can no longer use the git_tag pointer after this call.
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.
59 * @param tag the tag to close
61 GIT_EXTERN(void) git_tag_free(git_tag
*tag
);
64 * Get the id of a tag.
66 * @param tag a previously loaded tag.
67 * @return object identity for the tag.
69 GIT_EXTERN(const git_oid
*) git_tag_id(const git_tag
*tag
);
72 * Get the repository that contains the tag.
74 * @param tag A previously loaded tag.
75 * @return Repository that contains this tag.
77 GIT_EXTERN(git_repository
*) git_tag_owner(const git_tag
*tag
);
80 * Get the tagged object of a tag
82 * This method performs a repository lookup for the
83 * given object and returns it
85 * @param target_out pointer where to store the target
86 * @param tag a previously loaded tag.
87 * @return 0 or an error code
89 GIT_EXTERN(int) git_tag_target(git_object
**target_out
, const git_tag
*tag
);
92 * Get the OID of the tagged object of a tag
94 * @param tag a previously loaded tag.
95 * @return pointer to the OID
97 GIT_EXTERN(const git_oid
*) git_tag_target_id(const git_tag
*tag
);
100 * Get the type of a tag's tagged object
102 * @param tag a previously loaded tag.
103 * @return type of the tagged object
105 GIT_EXTERN(git_object_t
) git_tag_target_type(const git_tag
*tag
);
108 * Get the name of a tag
110 * @param tag a previously loaded tag.
111 * @return name of the tag
113 GIT_EXTERN(const char *) git_tag_name(const git_tag
*tag
);
116 * Get the tagger (author) of a tag
118 * @param tag a previously loaded tag.
119 * @return reference to the tag's author or NULL when unspecified
121 GIT_EXTERN(const git_signature
*) git_tag_tagger(const git_tag
*tag
);
124 * Get the message of a tag
126 * @param tag a previously loaded tag.
127 * @return message of the tag or NULL when unspecified
129 GIT_EXTERN(const char *) git_tag_message(const git_tag
*tag
);
133 * Create a new tag in the repository from an object
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.
139 * The message will not be cleaned up. This can be achieved
140 * through `git_message_prettify()`.
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.
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.
151 * @param repo Repository where to store the tag
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
157 * @param target Object to which this tag points. This object
158 * must belong to the given `repo`.
160 * @param tagger Signature of the tagger for this tag, and
161 * of the tagging time
163 * @param message Full message for this tag
165 * @param force Overwrite existing references
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
171 GIT_EXTERN(int) git_tag_create(
173 git_repository
*repo
,
174 const char *tag_name
,
175 const git_object
*target
,
176 const git_signature
*tagger
,
181 * Create a new tag in the object database pointing to a git_object
183 * The message will not be cleaned up. This can be achieved
184 * through `git_message_prettify()`.
186 * @param oid Pointer where to store the OID of the
189 * @param repo Repository where to store the tag
191 * @param tag_name Name for the tag
193 * @param target Object to which this tag points. This object
194 * must belong to the given `repo`.
196 * @param tagger Signature of the tagger for this tag, and
197 * of the tagging time
199 * @param message Full message for this tag
201 * @return 0 on success or an error code
203 GIT_EXTERN(int) git_tag_annotation_create(
205 git_repository
*repo
,
206 const char *tag_name
,
207 const git_object
*target
,
208 const git_signature
*tagger
,
209 const char *message
);
212 * Create a new tag in the repository from a buffer
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
220 GIT_EXTERN(int) git_tag_create_from_buffer(
222 git_repository
*repo
,
227 * Create a new lightweight tag pointing at a target object
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.
233 * The tag name will be checked for validity.
234 * See `git_tag_create()` for rules about valid names.
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.
241 * @param repo Repository where to store the lightweight tag
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
247 * @param target Object to which this tag points. This object
248 * must belong to the given `repo`.
250 * @param force Overwrite existing references
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
256 GIT_EXTERN(int) git_tag_create_lightweight(
258 git_repository
*repo
,
259 const char *tag_name
,
260 const git_object
*target
,
264 * Delete an existing tag reference.
266 * The tag name will be checked for validity.
267 * See `git_tag_create()` for rules about valid names.
269 * @param repo Repository where lives the tag
271 * @param tag_name Name of the tag to be deleted;
272 * this name is validated for consistency.
274 * @return 0 on success, GIT_EINVALIDSPEC or an error code
276 GIT_EXTERN(int) git_tag_delete(
277 git_repository
*repo
,
278 const char *tag_name
);
281 * Fill a list with all the tags in the Repository
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`.
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
293 GIT_EXTERN(int) git_tag_list(
294 git_strarray
*tag_names
,
295 git_repository
*repo
);
298 * Fill a list with all the tags in the Repository
299 * which name match a defined pattern
301 * If an empty pattern is provided, all the tags
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`.
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
315 GIT_EXTERN(int) git_tag_list_match(
316 git_strarray
*tag_names
,
318 git_repository
*repo
);
321 * Callback used to iterate over tag names
323 * @see git_tag_foreach
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
330 typedef int GIT_CALLBACK(git_tag_foreach_cb
)(const char *name
, git_oid
*oid
, void *payload
);
333 * Call callback `cb' for each tag in the repository
335 * @param repo Repository
336 * @param callback Callback function
337 * @param payload Pointer to callback data (optional)
339 GIT_EXTERN(int) git_tag_foreach(
340 git_repository
*repo
,
341 git_tag_foreach_cb callback
,
346 * Recursively peel a tag until a non tag git_object is found
348 * The retrieved `tag_target` object is owned by the repository
349 * and should be closed with the `git_object_free` method.
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
355 GIT_EXTERN(int) git_tag_peel(
356 git_object
**tag_target_out
,
360 * Create an in-memory copy of a tag. The copy must be explicitly
361 * free'd or it will leak.
363 * @param out Pointer to store the copy of the tag
364 * @param source Original tag to copy
366 GIT_EXTERN(int) git_tag_dup(git_tag
**out
, git_tag
*source
);