]>
Commit | Line | Data |
---|---|---|
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_commit_h__ | |
8 | #define INCLUDE_git_commit_h__ | |
9 | ||
10 | #include "common.h" | |
11 | #include "types.h" | |
12 | #include "oid.h" | |
13 | #include "object.h" | |
14 | ||
15 | /** | |
16 | * @file git2/commit.h | |
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 | ||
24 | /** | |
25 | * Lookup a commit object from a repository. | |
26 | * | |
27 | * The returned object should be released with `git_commit_free` when no | |
28 | * longer needed. | |
29 | * | |
30 | * @param commit pointer to the looked up commit | |
31 | * @param repo the repo to use when locating the commit. | |
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. | |
34 | * @return 0 or an error code | |
35 | */ | |
36 | GIT_EXTERN(int) git_commit_lookup( | |
37 | git_commit **commit, git_repository *repo, const git_oid *id); | |
38 | ||
39 | /** | |
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. | |
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. | |
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. | |
52 | * @param len the length of the short identifier | |
53 | * @return 0 or an error code | |
54 | */ | |
55 | GIT_EXTERN(int) git_commit_lookup_prefix( | |
56 | git_commit **commit, git_repository *repo, const git_oid *id, size_t len); | |
57 | ||
58 | /** | |
59 | * Close an open commit | |
60 | * | |
61 | * This is a wrapper around git_object_free() | |
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 | ||
70 | GIT_EXTERN(void) git_commit_free(git_commit *commit); | |
71 | ||
72 | /** | |
73 | * Get the id of a commit. | |
74 | * | |
75 | * @param commit a previously loaded commit. | |
76 | * @return object identity for the commit. | |
77 | */ | |
78 | GIT_EXTERN(const git_oid *) git_commit_id(const git_commit *commit); | |
79 | ||
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 | ||
88 | /** | |
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. | |
94 | * | |
95 | * @param commit a previously loaded commit. | |
96 | * @return NULL, or the encoding | |
97 | */ | |
98 | GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit); | |
99 | ||
100 | /** | |
101 | * Get the full message of a commit. | |
102 | * | |
103 | * The returned message will be slightly prettified by removing any | |
104 | * potential leading newlines. | |
105 | * | |
106 | * @param commit a previously loaded commit. | |
107 | * @return the message of a commit | |
108 | */ | |
109 | GIT_EXTERN(const char *) git_commit_message(const git_commit *commit); | |
110 | ||
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 | ||
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 | ||
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 | ||
143 | /** | |
144 | * Get the commit time (i.e. committer time) of a commit. | |
145 | * | |
146 | * @param commit a previously loaded commit. | |
147 | * @return the time of a commit | |
148 | */ | |
149 | GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit); | |
150 | ||
151 | /** | |
152 | * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit. | |
153 | * | |
154 | * @param commit a previously loaded commit. | |
155 | * @return positive or negative timezone offset, in minutes from UTC | |
156 | */ | |
157 | GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit); | |
158 | ||
159 | /** | |
160 | * Get the committer of a commit. | |
161 | * | |
162 | * @param commit a previously loaded commit. | |
163 | * @return the committer of a commit | |
164 | */ | |
165 | GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit); | |
166 | ||
167 | /** | |
168 | * Get the author of a commit. | |
169 | * | |
170 | * @param commit a previously loaded commit. | |
171 | * @return the author of a commit | |
172 | */ | |
173 | GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit); | |
174 | ||
175 | /** | |
176 | * Get the committer of a commit, using the mailmap to map names and email | |
177 | * addresses to canonical real names and email addresses. | |
178 | * | |
179 | * Call `git_signature_free` to free the signature. | |
180 | * | |
181 | * @param out a pointer to store the resolved signature. | |
182 | * @param commit a previously loaded commit. | |
183 | * @param mailmap the mailmap to resolve with. (may be NULL) | |
184 | * @return 0 or an error code | |
185 | */ | |
186 | GIT_EXTERN(int) git_commit_committer_with_mailmap( | |
187 | git_signature **out, const git_commit *commit, const git_mailmap *mailmap); | |
188 | ||
189 | /** | |
190 | * Get the author of a commit, using the mailmap to map names and email | |
191 | * addresses to canonical real names and email addresses. | |
192 | * | |
193 | * Call `git_signature_free` to free the signature. | |
194 | * | |
195 | * @param out a pointer to store the resolved signature. | |
196 | * @param commit a previously loaded commit. | |
197 | * @param mailmap the mailmap to resolve with. (may be NULL) | |
198 | * @return 0 or an error code | |
199 | */ | |
200 | GIT_EXTERN(int) git_commit_author_with_mailmap( | |
201 | git_signature **out, const git_commit *commit, const git_mailmap *mailmap); | |
202 | ||
203 | /** | |
204 | * Get the full raw text of the commit header. | |
205 | * | |
206 | * @param commit a previously loaded commit | |
207 | * @return the header text of the commit | |
208 | */ | |
209 | GIT_EXTERN(const char *) git_commit_raw_header(const git_commit *commit); | |
210 | ||
211 | /** | |
212 | * Get the tree pointed to by a commit. | |
213 | * | |
214 | * @param tree_out pointer where to store the tree object | |
215 | * @param commit a previously loaded commit. | |
216 | * @return 0 or an error code | |
217 | */ | |
218 | GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit); | |
219 | ||
220 | /** | |
221 | * Get the id of the tree pointed to by a commit. This differs from | |
222 | * `git_commit_tree` in that no attempts are made to fetch an object | |
223 | * from the ODB. | |
224 | * | |
225 | * @param commit a previously loaded commit. | |
226 | * @return the id of tree pointed to by commit. | |
227 | */ | |
228 | GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit); | |
229 | ||
230 | /** | |
231 | * Get the number of parents of this commit | |
232 | * | |
233 | * @param commit a previously loaded commit. | |
234 | * @return integer of count of parents | |
235 | */ | |
236 | GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit); | |
237 | ||
238 | /** | |
239 | * Get the specified parent of the commit. | |
240 | * | |
241 | * @param out Pointer where to store the parent commit | |
242 | * @param commit a previously loaded commit. | |
243 | * @param n the position of the parent (from 0 to `parentcount`) | |
244 | * @return 0 or an error code | |
245 | */ | |
246 | GIT_EXTERN(int) git_commit_parent( | |
247 | git_commit **out, | |
248 | const git_commit *commit, | |
249 | unsigned int n); | |
250 | ||
251 | /** | |
252 | * Get the oid of a specified parent for a commit. This is different from | |
253 | * `git_commit_parent`, which will attempt to load the parent commit from | |
254 | * the ODB. | |
255 | * | |
256 | * @param commit a previously loaded commit. | |
257 | * @param n the position of the parent (from 0 to `parentcount`) | |
258 | * @return the id of the parent, NULL on error. | |
259 | */ | |
260 | GIT_EXTERN(const git_oid *) git_commit_parent_id( | |
261 | const git_commit *commit, | |
262 | unsigned int n); | |
263 | ||
264 | /** | |
265 | * Get the commit object that is the <n>th generation ancestor | |
266 | * of the named commit object, following only the first parents. | |
267 | * The returned commit has to be freed by the caller. | |
268 | * | |
269 | * Passing `0` as the generation number returns another instance of the | |
270 | * base commit itself. | |
271 | * | |
272 | * @param ancestor Pointer where to store the ancestor commit | |
273 | * @param commit a previously loaded commit. | |
274 | * @param n the requested generation | |
275 | * @return 0 on success; GIT_ENOTFOUND if no matching ancestor exists | |
276 | * or an error code | |
277 | */ | |
278 | GIT_EXTERN(int) git_commit_nth_gen_ancestor( | |
279 | git_commit **ancestor, | |
280 | const git_commit *commit, | |
281 | unsigned int n); | |
282 | ||
283 | /** | |
284 | * Get an arbitrary header field | |
285 | * | |
286 | * @param out the buffer to fill; existing content will be | |
287 | * overwritten | |
288 | * @param commit the commit to look in | |
289 | * @param field the header field to return | |
290 | * @return 0 on succeess, GIT_ENOTFOUND if the field does not exist, | |
291 | * or an error code | |
292 | */ | |
293 | GIT_EXTERN(int) git_commit_header_field(git_buf *out, const git_commit *commit, const char *field); | |
294 | ||
295 | /** | |
296 | * Extract the signature from a commit | |
297 | * | |
298 | * If the id is not for a commit, the error class will be | |
299 | * `GIT_ERROR_INVALID`. If the commit does not have a signature, the | |
300 | * error class will be `GIT_ERROR_OBJECT`. | |
301 | * | |
302 | * @param signature the signature block; existing content will be | |
303 | * overwritten | |
304 | * @param signed_data signed data; this is the commit contents minus the signature block; | |
305 | * existing content will be overwritten | |
306 | * @param repo the repository in which the commit exists | |
307 | * @param commit_id the commit from which to extract the data | |
308 | * @param field the name of the header field containing the signature | |
309 | * block; pass `NULL` to extract the default 'gpgsig' | |
310 | * @return 0 on success, GIT_ENOTFOUND if the id is not for a commit | |
311 | * or the commit does not have a signature. | |
312 | */ | |
313 | GIT_EXTERN(int) git_commit_extract_signature(git_buf *signature, git_buf *signed_data, git_repository *repo, git_oid *commit_id, const char *field); | |
314 | ||
315 | /** | |
316 | * Create new commit in the repository from a list of `git_object` pointers | |
317 | * | |
318 | * The message will **not** be cleaned up automatically. You can do that | |
319 | * with the `git_message_prettify()` function. | |
320 | * | |
321 | * @param id Pointer in which to store the OID of the newly created commit | |
322 | * | |
323 | * @param repo Repository where to store the commit | |
324 | * | |
325 | * @param update_ref If not NULL, name of the reference that | |
326 | * will be updated to point to this commit. If the reference | |
327 | * is not direct, it will be resolved to a direct reference. | |
328 | * Use "HEAD" to update the HEAD of the current branch and | |
329 | * make it point to this commit. If the reference doesn't | |
330 | * exist yet, it will be created. If it does exist, the first | |
331 | * parent must be the tip of this branch. | |
332 | * | |
333 | * @param author Signature with author and author time of commit | |
334 | * | |
335 | * @param committer Signature with committer and * commit time of commit | |
336 | * | |
337 | * @param message_encoding The encoding for the message in the | |
338 | * commit, represented with a standard encoding name. | |
339 | * E.g. "UTF-8". If NULL, no encoding header is written and | |
340 | * UTF-8 is assumed. | |
341 | * | |
342 | * @param message Full message for this commit | |
343 | * | |
344 | * @param tree An instance of a `git_tree` object that will | |
345 | * be used as the tree for the commit. This tree object must | |
346 | * also be owned by the given `repo`. | |
347 | * | |
348 | * @param parent_count Number of parents for this commit | |
349 | * | |
350 | * @param parents Array of `parent_count` pointers to `git_commit` | |
351 | * objects that will be used as the parents for this commit. This | |
352 | * array may be NULL if `parent_count` is 0 (root commit). All the | |
353 | * given commits must be owned by the `repo`. | |
354 | * | |
355 | * @return 0 or an error code | |
356 | * The created commit will be written to the Object Database and | |
357 | * the given reference will be updated to point to it | |
358 | */ | |
359 | GIT_EXTERN(int) git_commit_create( | |
360 | git_oid *id, | |
361 | git_repository *repo, | |
362 | const char *update_ref, | |
363 | const git_signature *author, | |
364 | const git_signature *committer, | |
365 | const char *message_encoding, | |
366 | const char *message, | |
367 | const git_tree *tree, | |
368 | size_t parent_count, | |
369 | const git_commit *parents[]); | |
370 | ||
371 | /** | |
372 | * Create new commit in the repository using a variable argument list. | |
373 | * | |
374 | * The message will **not** be cleaned up automatically. You can do that | |
375 | * with the `git_message_prettify()` function. | |
376 | * | |
377 | * The parents for the commit are specified as a variable list of pointers | |
378 | * to `const git_commit *`. Note that this is a convenience method which may | |
379 | * not be safe to export for certain languages or compilers | |
380 | * | |
381 | * All other parameters remain the same as `git_commit_create()`. | |
382 | * | |
383 | * @see git_commit_create | |
384 | */ | |
385 | GIT_EXTERN(int) git_commit_create_v( | |
386 | git_oid *id, | |
387 | git_repository *repo, | |
388 | const char *update_ref, | |
389 | const git_signature *author, | |
390 | const git_signature *committer, | |
391 | const char *message_encoding, | |
392 | const char *message, | |
393 | const git_tree *tree, | |
394 | size_t parent_count, | |
395 | ...); | |
396 | ||
397 | /** | |
398 | * Amend an existing commit by replacing only non-NULL values. | |
399 | * | |
400 | * This creates a new commit that is exactly the same as the old commit, | |
401 | * except that any non-NULL values will be updated. The new commit has | |
402 | * the same parents as the old commit. | |
403 | * | |
404 | * The `update_ref` value works as in the regular `git_commit_create()`, | |
405 | * updating the ref to point to the newly rewritten commit. If you want | |
406 | * to amend a commit that is not currently the tip of the branch and then | |
407 | * rewrite the following commits to reach a ref, pass this as NULL and | |
408 | * update the rest of the commit chain and ref separately. | |
409 | * | |
410 | * Unlike `git_commit_create()`, the `author`, `committer`, `message`, | |
411 | * `message_encoding`, and `tree` parameters can be NULL in which case this | |
412 | * will use the values from the original `commit_to_amend`. | |
413 | * | |
414 | * All parameters have the same meanings as in `git_commit_create()`. | |
415 | * | |
416 | * @see git_commit_create | |
417 | */ | |
418 | GIT_EXTERN(int) git_commit_amend( | |
419 | git_oid *id, | |
420 | const git_commit *commit_to_amend, | |
421 | const char *update_ref, | |
422 | const git_signature *author, | |
423 | const git_signature *committer, | |
424 | const char *message_encoding, | |
425 | const char *message, | |
426 | const git_tree *tree); | |
427 | ||
428 | /** | |
429 | * Create a commit and write it into a buffer | |
430 | * | |
431 | * Create a commit as with `git_commit_create()` but instead of | |
432 | * writing it to the objectdb, write the contents of the object into a | |
433 | * buffer. | |
434 | * | |
435 | * @param out the buffer into which to write the commit object content | |
436 | * | |
437 | * @param repo Repository where the referenced tree and parents live | |
438 | * | |
439 | * @param author Signature with author and author time of commit | |
440 | * | |
441 | * @param committer Signature with committer and * commit time of commit | |
442 | * | |
443 | * @param message_encoding The encoding for the message in the | |
444 | * commit, represented with a standard encoding name. | |
445 | * E.g. "UTF-8". If NULL, no encoding header is written and | |
446 | * UTF-8 is assumed. | |
447 | * | |
448 | * @param message Full message for this commit | |
449 | * | |
450 | * @param tree An instance of a `git_tree` object that will | |
451 | * be used as the tree for the commit. This tree object must | |
452 | * also be owned by the given `repo`. | |
453 | * | |
454 | * @param parent_count Number of parents for this commit | |
455 | * | |
456 | * @param parents Array of `parent_count` pointers to `git_commit` | |
457 | * objects that will be used as the parents for this commit. This | |
458 | * array may be NULL if `parent_count` is 0 (root commit). All the | |
459 | * given commits must be owned by the `repo`. | |
460 | * | |
461 | * @return 0 or an error code | |
462 | */ | |
463 | GIT_EXTERN(int) git_commit_create_buffer( | |
464 | git_buf *out, | |
465 | git_repository *repo, | |
466 | const git_signature *author, | |
467 | const git_signature *committer, | |
468 | const char *message_encoding, | |
469 | const char *message, | |
470 | const git_tree *tree, | |
471 | size_t parent_count, | |
472 | const git_commit *parents[]); | |
473 | ||
474 | /** | |
475 | * Create a commit object from the given buffer and signature | |
476 | * | |
477 | * Given the unsigned commit object's contents, its signature and the | |
478 | * header field in which to store the signature, attach the signature | |
479 | * to the commit and write it into the given repository. | |
480 | * | |
481 | * @param out the resulting commit id | |
482 | * @param repo the repository to create the commit in. | |
483 | * @param commit_content the content of the unsigned commit object | |
484 | * @param signature the signature to add to the commit. Leave `NULL` | |
485 | * to create a commit without adding a signature field. | |
486 | * @param signature_field which header field should contain this | |
487 | * signature. Leave `NULL` for the default of "gpgsig" | |
488 | * @return 0 or an error code | |
489 | */ | |
490 | GIT_EXTERN(int) git_commit_create_with_signature( | |
491 | git_oid *out, | |
492 | git_repository *repo, | |
493 | const char *commit_content, | |
494 | const char *signature, | |
495 | const char *signature_field); | |
496 | ||
497 | /** | |
498 | * Create an in-memory copy of a commit. The copy must be explicitly | |
499 | * free'd or it will leak. | |
500 | * | |
501 | * @param out Pointer to store the copy of the commit | |
502 | * @param source Original commit to copy | |
503 | * @return 0 | |
504 | */ | |
505 | GIT_EXTERN(int) git_commit_dup(git_commit **out, git_commit *source); | |
506 | ||
507 | /** | |
508 | * Commit creation callback: used when a function is going to create | |
509 | * commits (for example, in `git_rebase_commit`) to allow callers to | |
510 | * override the commit creation behavior. For example, users may | |
511 | * wish to sign commits by providing this information to | |
512 | * `git_commit_create_buffer`, signing that buffer, then calling | |
513 | * `git_commit_create_with_signature`. The resultant commit id | |
514 | * should be set in the `out` object id parameter. | |
515 | * | |
516 | * @param out pointer that this callback will populate with the object | |
517 | * id of the commit that is created | |
518 | * @param author the author name and time of the commit | |
519 | * @param committer the committer name and time of the commit | |
520 | * @param message_encoding the encoding of the given message, or NULL | |
521 | * to assume UTF8 | |
522 | * @param message the commit message | |
523 | * @param tree the tree to be committed | |
524 | * @param parent_count the number of parents for this commit | |
525 | * @param parents the commit parents | |
526 | * @param payload the payload pointer in the rebase options | |
527 | * @return 0 if this callback has created the commit and populated the out | |
528 | * parameter, GIT_PASSTHROUGH if the callback has not created a | |
529 | * commit and wants the calling function to create the commit as | |
530 | * if no callback had been specified, any other value to stop | |
531 | * and return a failure | |
532 | */ | |
533 | typedef int (*git_commit_create_cb)( | |
534 | git_oid *out, | |
535 | const git_signature *author, | |
536 | const git_signature *committer, | |
537 | const char *message_encoding, | |
538 | const char *message, | |
539 | const git_tree *tree, | |
540 | size_t parent_count, | |
541 | const git_commit *parents[], | |
542 | void *payload); | |
543 | ||
544 | /** @} */ | |
545 | GIT_END_DECL | |
546 | #endif |