]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
bb742ede | 2 | * Copyright (C) 2009-2011 the libgit2 contributors |
f5918330 | 3 | * |
bb742ede VM |
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. | |
f5918330 | 6 | */ |
06160502 SP |
7 | #ifndef INCLUDE_git_commit_h__ |
8 | #define INCLUDE_git_commit_h__ | |
9 | ||
257bd746 | 10 | #include "common.h" |
d12299fe | 11 | #include "types.h" |
257bd746 | 12 | #include "oid.h" |
5de079b8 | 13 | #include "object.h" |
06160502 SP |
14 | |
15 | /** | |
f5918330 | 16 | * @file git2/commit.h |
06160502 SP |
17 | * @brief Git commit parsing, formatting routines |
18 | * @defgroup git_commit Git commit parsing, formatting routines | |
19 | * @ingroup Git | |
20 | * @{ | |
21 | */ | |
22 | GIT_BEGIN_DECL | |
23 | ||
06160502 | 24 | /** |
3315782c | 25 | * Lookup a commit object from a repository. |
088a731f | 26 | * |
1795f879 | 27 | * @param commit pointer to the looked up commit |
3315782c | 28 | * @param repo the repo to use when locating the commit. |
8add0153 VM |
29 | * @param id identity of the commit to locate. If the object is |
30 | * an annotated tag it will be peeled back to the commit. | |
d9111722 | 31 | * @return GIT_SUCCESS or an error code |
8add0153 | 32 | */ |
e52ed7a5 VM |
33 | GIT_INLINE(int) git_commit_lookup(git_commit **commit, git_repository *repo, const git_oid *id) |
34 | { | |
5de079b8 | 35 | return git_object_lookup((git_object **)commit, repo, id, GIT_OBJ_COMMIT); |
e52ed7a5 | 36 | } |
06160502 | 37 | |
790c6c95 MP |
38 | /** |
39 | * Lookup a commit object from a repository, | |
40 | * given a prefix of its identifier (short id). | |
41 | * | |
42 | * @see git_object_lookup_prefix | |
43 | * | |
44 | * @param commit pointer to the looked up commit | |
45 | * @param repo the repo to use when locating the commit. | |
46 | * @param id identity of the commit to locate. If the object is | |
47 | * an annotated tag it will be peeled back to the commit. | |
48 | * @param len the length of the short identifier | |
d9111722 | 49 | * @return GIT_SUCCESS or an error code |
790c6c95 MP |
50 | */ |
51 | GIT_INLINE(int) git_commit_lookup_prefix(git_commit **commit, git_repository *repo, const git_oid *id, unsigned len) | |
52 | { | |
53 | return git_object_lookup_prefix((git_object **)commit, repo, id, len, GIT_OBJ_COMMIT); | |
54 | } | |
55 | ||
b0b83135 CMN |
56 | /** |
57 | * Close an open commit | |
58 | * | |
59 | * This is a wrapper around git_object_close() | |
60 | * | |
61 | * IMPORTANT: | |
62 | * It *is* necessary to call this method when you stop | |
63 | * using a commit. Failure to do so will cause a memory leak. | |
64 | * | |
65 | * @param commit the commit to close | |
66 | */ | |
67 | ||
68 | GIT_INLINE(void) git_commit_close(git_commit *commit) | |
69 | { | |
c0ffe518 | 70 | git_object_close((git_object *) commit); |
b0b83135 CMN |
71 | } |
72 | ||
06160502 SP |
73 | /** |
74 | * Get the id of a commit. | |
72a3fe42 | 75 | * |
52f2390b | 76 | * @param commit a previously loaded commit. |
06160502 SP |
77 | * @return object identity for the commit. |
78 | */ | |
1e5dd572 | 79 | GIT_EXTERN(const git_oid *) git_commit_id(git_commit *commit); |
06160502 | 80 | |
52f2390b | 81 | /** |
5ae2f0c0 VM |
82 | * Get the encoding for the message of a commit, |
83 | * as a string representing a standard encoding name. | |
84 | * | |
85 | * The encoding may be NULL if the `encoding` header | |
86 | * in the commit is missing; in that case UTF-8 is assumed. | |
72a3fe42 | 87 | * |
52f2390b | 88 | * @param commit a previously loaded commit. |
5ae2f0c0 | 89 | * @return NULL, or the encoding |
52f2390b | 90 | */ |
5ae2f0c0 | 91 | GIT_EXTERN(const char *) git_commit_message_encoding(git_commit *commit); |
52f2390b VM |
92 | |
93 | /** | |
94 | * Get the full message of a commit. | |
72a3fe42 | 95 | * |
52f2390b VM |
96 | * @param commit a previously loaded commit. |
97 | * @return the message of a commit | |
98 | */ | |
99 | GIT_EXTERN(const char *) git_commit_message(git_commit *commit); | |
100 | ||
101 | /** | |
102 | * Get the commit time (i.e. committer time) of a commit. | |
72a3fe42 | 103 | * |
52f2390b VM |
104 | * @param commit a previously loaded commit. |
105 | * @return the time of a commit | |
106 | */ | |
56d8ca26 | 107 | GIT_EXTERN(git_time_t) git_commit_time(git_commit *commit); |
52f2390b | 108 | |
13710f1e | 109 | /** |
110 | * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit. | |
72a3fe42 | 111 | * |
13710f1e | 112 | * @param commit a previously loaded commit. |
113 | * @return positive or negative timezone offset, in minutes from UTC | |
114 | */ | |
c5846fbf | 115 | GIT_EXTERN(int) git_commit_time_offset(git_commit *commit); |
13710f1e | 116 | |
52f2390b VM |
117 | /** |
118 | * Get the committer of a commit. | |
72a3fe42 | 119 | * |
52f2390b VM |
120 | * @param commit a previously loaded commit. |
121 | * @return the committer of a commit | |
122 | */ | |
638c2ca4 | 123 | GIT_EXTERN(const git_signature *) git_commit_committer(git_commit *commit); |
52f2390b VM |
124 | |
125 | /** | |
126 | * Get the author of a commit. | |
72a3fe42 | 127 | * |
52f2390b VM |
128 | * @param commit a previously loaded commit. |
129 | * @return the author of a commit | |
130 | */ | |
638c2ca4 | 131 | GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit); |
52f2390b VM |
132 | |
133 | /** | |
134 | * Get the tree pointed to by a commit. | |
72a3fe42 | 135 | * |
6b2a1941 | 136 | * @param tree_out pointer where to store the tree object |
52f2390b | 137 | * @param commit a previously loaded commit. |
d9111722 | 138 | * @return GIT_SUCCESS or an error code |
52f2390b | 139 | */ |
6b2a1941 | 140 | GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit); |
52f2390b | 141 | |
5924b282 S |
142 | /** |
143 | * Get the id of the tree pointed to by a commit. This differs from | |
144 | * `git_commit_tree` in that no attempts are made to fetch an object | |
145 | * from the ODB. | |
146 | * | |
147 | * @param commit a previously loaded commit. | |
148 | * @return the id of tree pointed to by commit. | |
149 | */ | |
150 | GIT_EXTERN(const git_oid *) git_commit_tree_oid(git_commit *commit); | |
151 | ||
12114415 JL |
152 | /** |
153 | * Get the number of parents of this commit | |
154 | * | |
155 | * @param commit a previously loaded commit. | |
156 | * @return integer of count of parents | |
157 | */ | |
158 | GIT_EXTERN(unsigned int) git_commit_parentcount(git_commit *commit); | |
159 | ||
eb095435 JL |
160 | /** |
161 | * Get the specified parent of the commit. | |
6b2a1941 VM |
162 | * |
163 | * @param parent Pointer where to store the parent commit | |
eb095435 | 164 | * @param commit a previously loaded commit. |
6b2a1941 | 165 | * @param n the position of the parent (from 0 to `parentcount`) |
d9111722 | 166 | * @return GIT_SUCCESS or an error code |
eb095435 | 167 | */ |
6b2a1941 | 168 | GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsigned int n); |
eb095435 | 169 | |
5924b282 S |
170 | /** |
171 | * Get the oid of a specified parent for a commit. This is different from | |
172 | * `git_commit_parent`, which will attempt to load the parent commit from | |
173 | * the ODB. | |
174 | * | |
175 | * @param commit a previously loaded commit. | |
176 | * @param n the position of the parent (from 0 to `parentcount`) | |
177 | * @return the id of the parent, NULL on error. | |
178 | */ | |
179 | GIT_EXTERN(const git_oid *) git_commit_parent_oid(git_commit *commit, unsigned int n); | |
72a3fe42 | 180 | |
0d95f32c | 181 | /** |
d5afc039 VM |
182 | * Create a new commit in the repository using `git_object` |
183 | * instances as parameters. | |
72a3fe42 | 184 | * |
72a3fe42 VM |
185 | * @param oid Pointer where to store the OID of the |
186 | * newly created commit | |
187 | * | |
188 | * @param repo Repository where to store the commit | |
189 | * | |
190 | * @param update_ref If not NULL, name of the reference that | |
191 | * will be updated to point to this commit. If the reference | |
192 | * is not direct, it will be resolved to a direct reference. | |
193 | * Use "HEAD" to update the HEAD of the current branch and | |
194 | * make it point to this commit | |
195 | * | |
196 | * @param author Signature representing the author and the authory | |
197 | * time of this commit | |
198 | * | |
199 | * @param committer Signature representing the committer and the | |
200 | * commit time of this commit | |
201 | * | |
5ae2f0c0 VM |
202 | * @param message_encoding The encoding for the message in the |
203 | * commit, represented with a standard encoding name. | |
204 | * E.g. "UTF-8". If NULL, no encoding header is written and | |
205 | * UTF-8 is assumed. | |
206 | * | |
72a3fe42 VM |
207 | * @param message Full message for this commit |
208 | * | |
d5afc039 VM |
209 | * @param tree An instance of a `git_tree` object that will |
210 | * be used as the tree for the commit. This tree object must | |
211 | * also be owned by the given `repo`. | |
72a3fe42 VM |
212 | * |
213 | * @param parent_count Number of parents for this commit | |
214 | * | |
d5afc039 VM |
215 | * @param parents[] Array of `parent_count` pointers to `git_commit` |
216 | * objects that will be used as the parents for this commit. This | |
217 | * array may be NULL if `parent_count` is 0 (root commit). All the | |
218 | * given commits must be owned by the `repo`. | |
72a3fe42 | 219 | * |
d9111722 | 220 | * @return GIT_SUCCESS or an error code |
72a3fe42 VM |
221 | * The created commit will be written to the Object Database and |
222 | * the given reference will be updated to point to it | |
0c3596f1 | 223 | */ |
72a3fe42 | 224 | GIT_EXTERN(int) git_commit_create( |
72a3fe42 VM |
225 | git_oid *oid, |
226 | git_repository *repo, | |
227 | const char *update_ref, | |
228 | const git_signature *author, | |
229 | const git_signature *committer, | |
5ae2f0c0 | 230 | const char *message_encoding, |
72a3fe42 VM |
231 | const char *message, |
232 | const git_tree *tree, | |
233 | int parent_count, | |
234 | const git_commit *parents[]); | |
0c3596f1 | 235 | |
0d95f32c | 236 | /** |
d5afc039 VM |
237 | * Create a new commit in the repository using a variable |
238 | * argument list. | |
72a3fe42 VM |
239 | * |
240 | * The parents for the commit are specified as a variable | |
241 | * list of pointers to `const git_commit *`. Note that this | |
242 | * is a convenience method which may not be safe to export | |
243 | * for certain languages or compilers | |
244 | * | |
245 | * All other parameters remain the same | |
246 | * | |
247 | * @see git_commit_create | |
0c3596f1 | 248 | */ |
72a3fe42 VM |
249 | GIT_EXTERN(int) git_commit_create_v( |
250 | git_oid *oid, | |
251 | git_repository *repo, | |
252 | const char *update_ref, | |
253 | const git_signature *author, | |
254 | const git_signature *committer, | |
5ae2f0c0 | 255 | const char *message_encoding, |
72a3fe42 | 256 | const char *message, |
d5afc039 | 257 | const git_tree *tree, |
72a3fe42 VM |
258 | int parent_count, |
259 | ...); | |
0c3596f1 | 260 | |
06160502 SP |
261 | /** @} */ |
262 | GIT_END_DECL | |
263 | #endif |