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