]>
Commit | Line | Data |
---|---|---|
f5918330 | 1 | /* |
359fc2d2 | 2 | * Copyright (C) the libgit2 contributors. All rights reserved. |
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 | * |
b2d3efcb RB |
27 | * The returned object should be released with `git_commit_free` when no |
28 | * longer needed. | |
29 | * | |
1795f879 | 30 | * @param commit pointer to the looked up commit |
3315782c | 31 | * @param repo the repo to use when locating the commit. |
87d9869f VM |
32 | * @param id identity of the commit to locate. If the object is |
33 | * an annotated tag it will be peeled back to the commit. | |
e172cf08 | 34 | * @return 0 or an error code |
8add0153 | 35 | */ |
b2d3efcb RB |
36 | GIT_EXTERN(int) git_commit_lookup( |
37 | git_commit **commit, git_repository *repo, const git_oid *id); | |
06160502 | 38 | |
790c6c95 | 39 | /** |
b2d3efcb RB |
40 | * Lookup a commit object from a repository, given a prefix of its |
41 | * identifier (short id). | |
42 | * | |
43 | * The returned object should be released with `git_commit_free` when no | |
44 | * longer needed. | |
790c6c95 MP |
45 | * |
46 | * @see git_object_lookup_prefix | |
47 | * | |
48 | * @param commit pointer to the looked up commit | |
49 | * @param repo the repo to use when locating the commit. | |
87d9869f VM |
50 | * @param id identity of the commit to locate. If the object is |
51 | * an annotated tag it will be peeled back to the commit. | |
790c6c95 | 52 | * @param len the length of the short identifier |
e172cf08 | 53 | * @return 0 or an error code |
790c6c95 | 54 | */ |
b2d3efcb RB |
55 | GIT_EXTERN(int) git_commit_lookup_prefix( |
56 | git_commit **commit, git_repository *repo, const git_oid *id, size_t len); | |
790c6c95 | 57 | |
b0b83135 CMN |
58 | /** |
59 | * Close an open commit | |
60 | * | |
45e79e37 | 61 | * This is a wrapper around git_object_free() |
b0b83135 CMN |
62 | * |
63 | * IMPORTANT: | |
64 | * It *is* necessary to call this method when you stop | |
65 | * using a commit. Failure to do so will cause a memory leak. | |
66 | * | |
67 | * @param commit the commit to close | |
68 | */ | |
69 | ||
0b726701 | 70 | GIT_EXTERN(void) git_commit_free(git_commit *commit); |
b0b83135 | 71 | |
06160502 SP |
72 | /** |
73 | * Get the id of a commit. | |
72a3fe42 | 74 | * |
52f2390b | 75 | * @param commit a previously loaded commit. |
06160502 SP |
76 | * @return object identity for the commit. |
77 | */ | |
0b726701 | 78 | GIT_EXTERN(const git_oid *) git_commit_id(const git_commit *commit); |
06160502 | 79 | |
6e865996 DI |
80 | /** |
81 | * Get the repository that contains the commit. | |
82 | * | |
83 | * @param commit A previously loaded commit. | |
84 | * @return Repository that contains this commit. | |
85 | */ | |
86 | GIT_EXTERN(git_repository *) git_commit_owner(const git_commit *commit); | |
87 | ||
52f2390b | 88 | /** |
5ae2f0c0 VM |
89 | * Get the encoding for the message of a commit, |
90 | * as a string representing a standard encoding name. | |
91 | * | |
92 | * The encoding may be NULL if the `encoding` header | |
93 | * in the commit is missing; in that case UTF-8 is assumed. | |
72a3fe42 | 94 | * |
52f2390b | 95 | * @param commit a previously loaded commit. |
5ae2f0c0 | 96 | * @return NULL, or the encoding |
52f2390b | 97 | */ |
cfbe4be3 | 98 | GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit); |
52f2390b VM |
99 | |
100 | /** | |
101 | * Get the full message of a commit. | |
72a3fe42 | 102 | * |
598f069b | 103 | * The returned message will be slightly prettified by removing any |
104 | * potential leading newlines. | |
105 | * | |
52f2390b VM |
106 | * @param commit a previously loaded commit. |
107 | * @return the message of a commit | |
108 | */ | |
cfbe4be3 | 109 | GIT_EXTERN(const char *) git_commit_message(const git_commit *commit); |
52f2390b | 110 | |
598f069b | 111 | /** |
112 | * Get the full raw message of a commit. | |
113 | * | |
114 | * @param commit a previously loaded commit. | |
115 | * @return the raw message of a commit | |
116 | */ | |
117 | GIT_EXTERN(const char *) git_commit_message_raw(const git_commit *commit); | |
118 | ||
300d192f ET |
119 | /** |
120 | * Get the short "summary" of the git commit message. | |
121 | * | |
122 | * The returned message is the summary of the commit, comprising the | |
123 | * first paragraph of the message with whitespace trimmed and squashed. | |
124 | * | |
125 | * @param commit a previously loaded commit. | |
126 | * @return the summary of a commit or NULL on error | |
127 | */ | |
128 | GIT_EXTERN(const char *) git_commit_summary(git_commit *commit); | |
129 | ||
7f8fe1d4 PS |
130 | /** |
131 | * Get the long "body" of the git commit message. | |
132 | * | |
133 | * The returned message is the body of the commit, comprising | |
134 | * everything but the first paragraph of the message. Leading and | |
135 | * trailing whitespaces are trimmed. | |
136 | * | |
137 | * @param commit a previously loaded commit. | |
138 | * @return the body of a commit or NULL when no the message only | |
139 | * consists of a summary | |
140 | */ | |
141 | GIT_EXTERN(const char *) git_commit_body(git_commit *commit); | |
142 | ||
52f2390b VM |
143 | /** |
144 | * Get the commit time (i.e. committer time) of a commit. | |
72a3fe42 | 145 | * |
52f2390b VM |
146 | * @param commit a previously loaded commit. |
147 | * @return the time of a commit | |
148 | */ | |
cfbe4be3 | 149 | GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit); |
52f2390b | 150 | |
13710f1e | 151 | /** |
152 | * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit. | |
72a3fe42 | 153 | * |
13710f1e | 154 | * @param commit a previously loaded commit. |
155 | * @return positive or negative timezone offset, in minutes from UTC | |
156 | */ | |
cfbe4be3 | 157 | GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit); |
13710f1e | 158 | |
52f2390b VM |
159 | /** |
160 | * Get the committer of a commit. | |
72a3fe42 | 161 | * |
52f2390b VM |
162 | * @param commit a previously loaded commit. |
163 | * @return the committer of a commit | |
164 | */ | |
cfbe4be3 | 165 | GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit); |
52f2390b VM |
166 | |
167 | /** | |
168 | * Get the author of a commit. | |
72a3fe42 | 169 | * |
52f2390b VM |
170 | * @param commit a previously loaded commit. |
171 | * @return the author of a commit | |
172 | */ | |
cfbe4be3 | 173 | GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit); |
52f2390b | 174 | |
f094f905 RB |
175 | /** |
176 | * Get the full raw text of the commit header. | |
177 | * | |
178 | * @param commit a previously loaded commit | |
179 | * @return the header text of the commit | |
180 | */ | |
181 | GIT_EXTERN(const char *) git_commit_raw_header(const git_commit *commit); | |
182 | ||
52f2390b VM |
183 | /** |
184 | * Get the tree pointed to by a commit. | |
72a3fe42 | 185 | * |
6b2a1941 | 186 | * @param tree_out pointer where to store the tree object |
52f2390b | 187 | * @param commit a previously loaded commit. |
e172cf08 | 188 | * @return 0 or an error code |
52f2390b | 189 | */ |
cfbe4be3 | 190 | GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit); |
52f2390b | 191 | |
5924b282 S |
192 | /** |
193 | * Get the id of the tree pointed to by a commit. This differs from | |
194 | * `git_commit_tree` in that no attempts are made to fetch an object | |
195 | * from the ODB. | |
196 | * | |
197 | * @param commit a previously loaded commit. | |
198 | * @return the id of tree pointed to by commit. | |
199 | */ | |
cfbe4be3 | 200 | GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit); |
5924b282 | 201 | |
12114415 JL |
202 | /** |
203 | * Get the number of parents of this commit | |
204 | * | |
205 | * @param commit a previously loaded commit. | |
206 | * @return integer of count of parents | |
207 | */ | |
cfbe4be3 | 208 | GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit); |
12114415 | 209 | |
eb095435 JL |
210 | /** |
211 | * Get the specified parent of the commit. | |
6b2a1941 | 212 | * |
cfbe4be3 | 213 | * @param out Pointer where to store the parent commit |
eb095435 | 214 | * @param commit a previously loaded commit. |
6b2a1941 | 215 | * @param n the position of the parent (from 0 to `parentcount`) |
e172cf08 | 216 | * @return 0 or an error code |
eb095435 | 217 | */ |
58206c9a RB |
218 | GIT_EXTERN(int) git_commit_parent( |
219 | git_commit **out, | |
220 | const git_commit *commit, | |
221 | unsigned int n); | |
eb095435 | 222 | |
5924b282 S |
223 | /** |
224 | * Get the oid of a specified parent for a commit. This is different from | |
225 | * `git_commit_parent`, which will attempt to load the parent commit from | |
226 | * the ODB. | |
227 | * | |
228 | * @param commit a previously loaded commit. | |
229 | * @param n the position of the parent (from 0 to `parentcount`) | |
230 | * @return the id of the parent, NULL on error. | |
231 | */ | |
58206c9a RB |
232 | GIT_EXTERN(const git_oid *) git_commit_parent_id( |
233 | const git_commit *commit, | |
234 | unsigned int n); | |
72a3fe42 | 235 | |
b1aca6ea | 236 | /** |
237 | * Get the commit object that is the <n>th generation ancestor | |
238 | * of the named commit object, following only the first parents. | |
239 | * The returned commit has to be freed by the caller. | |
240 | * | |
241 | * Passing `0` as the generation number returns another instance of the | |
242 | * base commit itself. | |
243 | * | |
244 | * @param ancestor Pointer where to store the ancestor commit | |
245 | * @param commit a previously loaded commit. | |
246 | * @param n the requested generation | |
247 | * @return 0 on success; GIT_ENOTFOUND if no matching ancestor exists | |
248 | * or an error code | |
249 | */ | |
1ebe432e | 250 | GIT_EXTERN(int) git_commit_nth_gen_ancestor( |
b1aca6ea | 251 | git_commit **ancestor, |
252 | const git_commit *commit, | |
253 | unsigned int n); | |
254 | ||
a3f42fe8 CMN |
255 | /** |
256 | * Get an arbitrary header field | |
257 | * | |
258 | * @param out the buffer to fill | |
259 | * @param commit the commit to look in | |
260 | * @param field the header field to return | |
261 | * @return 0 on succeess, GIT_ENOTFOUND if the field does not exist, | |
262 | * or an error code | |
263 | */ | |
264 | GIT_EXTERN(int) git_commit_header_field(git_buf *out, const git_commit *commit, const char *field); | |
265 | ||
0d95f32c | 266 | /** |
9233b3de | 267 | * Create new commit in the repository from a list of `git_object` pointers |
72a3fe42 | 268 | * |
80c29fe9 RB |
269 | * The message will **not** be cleaned up automatically. You can do that |
270 | * with the `git_message_prettify()` function. | |
458b9450 | 271 | * |
9233b3de | 272 | * @param id Pointer in which to store the OID of the newly created commit |
72a3fe42 VM |
273 | * |
274 | * @param repo Repository where to store the commit | |
275 | * | |
276 | * @param update_ref If not NULL, name of the reference that | |
277 | * will be updated to point to this commit. If the reference | |
278 | * is not direct, it will be resolved to a direct reference. | |
279 | * Use "HEAD" to update the HEAD of the current branch and | |
b4b79ac3 | 280 | * make it point to this commit. If the reference doesn't |
217c029b CMN |
281 | * exist yet, it will be created. If it does exist, the first |
282 | * parent must be the tip of this branch. | |
72a3fe42 | 283 | * |
9233b3de | 284 | * @param author Signature with author and author time of commit |
72a3fe42 | 285 | * |
9233b3de | 286 | * @param committer Signature with committer and * commit time of commit |
72a3fe42 | 287 | * |
5ae2f0c0 | 288 | * @param message_encoding The encoding for the message in the |
9233b3de RB |
289 | * commit, represented with a standard encoding name. |
290 | * E.g. "UTF-8". If NULL, no encoding header is written and | |
291 | * UTF-8 is assumed. | |
5ae2f0c0 | 292 | * |
72a3fe42 VM |
293 | * @param message Full message for this commit |
294 | * | |
d5afc039 | 295 | * @param tree An instance of a `git_tree` object that will |
9233b3de RB |
296 | * be used as the tree for the commit. This tree object must |
297 | * also be owned by the given `repo`. | |
72a3fe42 VM |
298 | * |
299 | * @param parent_count Number of parents for this commit | |
300 | * | |
e1967164 | 301 | * @param parents Array of `parent_count` pointers to `git_commit` |
9233b3de RB |
302 | * objects that will be used as the parents for this commit. This |
303 | * array may be NULL if `parent_count` is 0 (root commit). All the | |
304 | * given commits must be owned by the `repo`. | |
72a3fe42 | 305 | * |
e172cf08 | 306 | * @return 0 or an error code |
72a3fe42 VM |
307 | * The created commit will be written to the Object Database and |
308 | * the given reference will be updated to point to it | |
0c3596f1 | 309 | */ |
72a3fe42 | 310 | GIT_EXTERN(int) git_commit_create( |
9233b3de RB |
311 | git_oid *id, |
312 | git_repository *repo, | |
313 | const char *update_ref, | |
314 | const git_signature *author, | |
315 | const git_signature *committer, | |
316 | const char *message_encoding, | |
317 | const char *message, | |
318 | const git_tree *tree, | |
80c29fe9 | 319 | size_t parent_count, |
9233b3de | 320 | const git_commit *parents[]); |
0c3596f1 | 321 | |
0d95f32c | 322 | /** |
9233b3de | 323 | * Create new commit in the repository using a variable argument list. |
72a3fe42 | 324 | * |
80c29fe9 RB |
325 | * The message will **not** be cleaned up automatically. You can do that |
326 | * with the `git_message_prettify()` function. | |
458b9450 | 327 | * |
9233b3de RB |
328 | * The parents for the commit are specified as a variable list of pointers |
329 | * to `const git_commit *`. Note that this is a convenience method which may | |
330 | * not be safe to export for certain languages or compilers | |
72a3fe42 | 331 | * |
80c29fe9 | 332 | * All other parameters remain the same as `git_commit_create()`. |
72a3fe42 VM |
333 | * |
334 | * @see git_commit_create | |
0c3596f1 | 335 | */ |
72a3fe42 | 336 | GIT_EXTERN(int) git_commit_create_v( |
9233b3de RB |
337 | git_oid *id, |
338 | git_repository *repo, | |
339 | const char *update_ref, | |
340 | const git_signature *author, | |
341 | const git_signature *committer, | |
342 | const char *message_encoding, | |
343 | const char *message, | |
344 | const git_tree *tree, | |
80c29fe9 | 345 | size_t parent_count, |
9233b3de | 346 | ...); |
92550398 | 347 | |
80c29fe9 RB |
348 | /** |
349 | * Amend an existing commit by replacing only non-NULL values. | |
350 | * | |
351 | * This creates a new commit that is exactly the same as the old commit, | |
352 | * except that any non-NULL values will be updated. The new commit has | |
353 | * the same parents as the old commit. | |
354 | * | |
355 | * The `update_ref` value works as in the regular `git_commit_create()`, | |
356 | * updating the ref to point to the newly rewritten commit. If you want | |
217c029b | 357 | * to amend a commit that is not currently the tip of the branch and then |
80c29fe9 RB |
358 | * rewrite the following commits to reach a ref, pass this as NULL and |
359 | * update the rest of the commit chain and ref separately. | |
360 | * | |
361 | * Unlike `git_commit_create()`, the `author`, `committer`, `message`, | |
362 | * `message_encoding`, and `tree` parameters can be NULL in which case this | |
363 | * will use the values from the original `commit_to_amend`. | |
364 | * | |
365 | * All parameters have the same meanings as in `git_commit_create()`. | |
366 | * | |
367 | * @see git_commit_create | |
368 | */ | |
369 | GIT_EXTERN(int) git_commit_amend( | |
370 | git_oid *id, | |
371 | const git_commit *commit_to_amend, | |
372 | const char *update_ref, | |
373 | const git_signature *author, | |
374 | const git_signature *committer, | |
375 | const char *message_encoding, | |
376 | const char *message, | |
377 | const git_tree *tree); | |
378 | ||
06160502 SP |
379 | /** @} */ |
380 | GIT_END_DECL | |
381 | #endif |