include/git2/annotated_commit.h

   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_annotated_commit_h__
   8 #define INCLUDE_git_annotated_commit_h__
   9
  10 #include "common.h"
  11 #include "repository.h"
  12 #include "types.h"
  13
  14 /**
  15  * @file git2/annotated_commit.h
  16  * @brief Git annotated commit routines
  17  * @defgroup git_annotated_commit Git annotated commit routines
  18  * @ingroup Git
  19  * @{
  20  */
  21 GIT_BEGIN_DECL
  22
  23 /**
  24  * Creates a `git_annotated_commit` from the given reference.
  25  * The resulting git_annotated_commit must be freed with
  26  * `git_annotated_commit_free`.
  27  *
  28  * @param out pointer to store the git_annotated_commit result in
  29  * @param repo repository that contains the given reference
  30  * @param ref reference to use to lookup the git_annotated_commit
  31  * @return 0 on success or error code
  32  */
  33 GIT_EXTERN(int) git_annotated_commit_from_ref(
  34         git_annotated_commit **out,
  35         git_repository *repo,
  36         const git_reference *ref);
  37
  38 /**
  39  * Creates a `git_annotated_commit` from the given fetch head data.
  40  * The resulting git_annotated_commit must be freed with
  41  * `git_annotated_commit_free`.
  42  *
  43  * @param out pointer to store the git_annotated_commit result in
  44  * @param repo repository that contains the given commit
  45  * @param branch_name name of the (remote) branch
  46  * @param remote_url url of the remote
  47  * @param id the commit object id of the remote branch
  48  * @return 0 on success or error code
  49  */
  50 GIT_EXTERN(int) git_annotated_commit_from_fetchhead(
  51         git_annotated_commit **out,
  52         git_repository *repo,
  53         const char *branch_name,
  54         const char *remote_url,
  55         const git_oid *id);
  56
  57 /**
  58  * Creates a `git_annotated_commit` from the given commit id.
  59  * The resulting git_annotated_commit must be freed with
  60  * `git_annotated_commit_free`.
  61  *
  62  * An annotated commit contains information about how it was
  63  * looked up, which may be useful for functions like merge or
  64  * rebase to provide context to the operation.  For example,
  65  * conflict files will include the name of the source or target
  66  * branches being merged.  It is therefore preferable to use the
  67  * most specific function (eg `git_annotated_commit_from_ref`)
  68  * instead of this one when that data is known.
  69  *
  70  * @param out pointer to store the git_annotated_commit result in
  71  * @param repo repository that contains the given commit
  72  * @param id the commit object id to lookup
  73  * @return 0 on success or error code
  74  */
  75 GIT_EXTERN(int) git_annotated_commit_lookup(
  76         git_annotated_commit **out,
  77         git_repository *repo,
  78         const git_oid *id);
  79
  80 /**
  81  * Creates a `git_annotated_comit` from a revision string.
  82  *
  83  * See `man gitrevisions`, or
  84  * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for
  85  * information on the syntax accepted.
  86  *
  87  * @param out pointer to store the git_annotated_commit result in
  88  * @param repo repository that contains the given commit
  89  * @param revspec the extended sha syntax string to use to lookup the commit
  90  * @return 0 on success or error code
  91  */
  92 GIT_EXTERN(int) git_annotated_commit_from_revspec(
  93         git_annotated_commit **out,
  94         git_repository *repo,
  95         const char *revspec);
  96
  97 /**
  98  * Gets the commit ID that the given `git_annotated_commit` refers to.
  99  *
 100  * @param commit the given annotated commit
 101  * @return commit id
 102  */
 103 GIT_EXTERN(const git_oid *) git_annotated_commit_id(
 104         const git_annotated_commit *commit);
 105
 106 /**
 107  * Get the refname that the given `git_annotated_commit` refers to.
 108  *
 109  * @param commit the given annotated commit
 110  * @return ref name.
 111  */
 112 GIT_EXTERN(const char *) git_annotated_commit_ref(
 113         const git_annotated_commit *commit);
 114
 115 /**
 116  * Frees a `git_annotated_commit`.
 117  *
 118  * @param commit annotated commit to free
 119  */
 120 GIT_EXTERN(void) git_annotated_commit_free(
 121         git_annotated_commit *commit);
 122
 123 /** @} */
 124 GIT_END_DECL
 125 #endif