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_commit` 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 126
