include/git2/annotated_commit.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_annotated_commit_h__
0008 #define INCLUDE_git_annotated_commit_h__
0009
0010 #include "common.h"
0011 #include "repository.h"
0012 #include "types.h"
0013
0014 /**
0015  * @file git2/annotated_commit.h
0016  * @brief Git annotated commit routines
0017  * @defgroup git_annotated_commit Git annotated commit routines
0018  * @ingroup Git
0019  * @{
0020  */
0021 GIT_BEGIN_DECL
0022
0023 /**
0024  * Creates a `git_annotated_commit` from the given reference.
0025  * The resulting git_annotated_commit must be freed with
0026  * `git_annotated_commit_free`.
0027  *
0028  * @param out pointer to store the git_annotated_commit result in
0029  * @param repo repository that contains the given reference
0030  * @param ref reference to use to lookup the git_annotated_commit
0031  * @return 0 on success or error code
0032  */
0033 GIT_EXTERN(int) git_annotated_commit_from_ref(
0034     git_annotated_commit **out,
0035     git_repository *repo,
0036     const git_reference *ref);
0037
0038 /**
0039  * Creates a `git_annotated_commit` from the given fetch head data.
0040  * The resulting git_annotated_commit must be freed with
0041  * `git_annotated_commit_free`.
0042  *
0043  * @param out pointer to store the git_annotated_commit result in
0044  * @param repo repository that contains the given commit
0045  * @param branch_name name of the (remote) branch
0046  * @param remote_url url of the remote
0047  * @param id the commit object id of the remote branch
0048  * @return 0 on success or error code
0049  */
0050 GIT_EXTERN(int) git_annotated_commit_from_fetchhead(
0051     git_annotated_commit **out,
0052     git_repository *repo,
0053     const char *branch_name,
0054     const char *remote_url,
0055     const git_oid *id);
0056
0057 /**
0058  * Creates a `git_annotated_commit` from the given commit id.
0059  * The resulting git_annotated_commit must be freed with
0060  * `git_annotated_commit_free`.
0061  *
0062  * An annotated commit contains information about how it was
0063  * looked up, which may be useful for functions like merge or
0064  * rebase to provide context to the operation.  For example,
0065  * conflict files will include the name of the source or target
0066  * branches being merged.  It is therefore preferable to use the
0067  * most specific function (eg `git_annotated_commit_from_ref`)
0068  * instead of this one when that data is known.
0069  *
0070  * @param out pointer to store the git_annotated_commit result in
0071  * @param repo repository that contains the given commit
0072  * @param id the commit object id to lookup
0073  * @return 0 on success or error code
0074  */
0075 GIT_EXTERN(int) git_annotated_commit_lookup(
0076     git_annotated_commit **out,
0077     git_repository *repo,
0078     const git_oid *id);
0079
0080 /**
0081  * Creates a `git_annotated_commit` from a revision string.
0082  *
0083  * See `man gitrevisions`, or
0084  * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for
0085  * information on the syntax accepted.
0086  *
0087  * @param out pointer to store the git_annotated_commit result in
0088  * @param repo repository that contains the given commit
0089  * @param revspec the extended sha syntax string to use to lookup the commit
0090  * @return 0 on success or error code
0091  */
0092 GIT_EXTERN(int) git_annotated_commit_from_revspec(
0093     git_annotated_commit **out,
0094     git_repository *repo,
0095     const char *revspec);
0096
0097 /**
0098  * Gets the commit ID that the given `git_annotated_commit` refers to.
0099  *
0100  * @param commit the given annotated commit
0101  * @return commit id
0102  */
0103 GIT_EXTERN(const git_oid *) git_annotated_commit_id(
0104     const git_annotated_commit *commit);
0105
0106 /**
0107  * Get the refname that the given `git_annotated_commit` refers to.
0108  *
0109  * @param commit the given annotated commit
0110  * @return ref name.
0111  */
0112 GIT_EXTERN(const char *) git_annotated_commit_ref(
0113     const git_annotated_commit *commit);
0114
0115 /**
0116  * Frees a `git_annotated_commit`.
0117  *
0118  * @param commit annotated commit to free
0119  */
0120 GIT_EXTERN(void) git_annotated_commit_free(
0121     git_annotated_commit *commit);
0122
0123 /** @} */
0124 GIT_END_DECL
0125 #endif