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 module libgit2_d.commit; 8 9 10 private static import libgit2_d.buffer; 11 private static import libgit2_d.oid; 12 private static import libgit2_d.types; 13 14 /** 15 * @file git2/commit.h 16 * @brief Git commit parsing, formatting routines 17 * @defgroup git_commit Git commit parsing, formatting routines 18 * @ingroup Git 19 * @{ 20 */ 21 extern (C): 22 nothrow @nogc: 23 public: 24 25 /** 26 * Lookup a commit object from a repository. 27 * 28 * The returned object should be released with `git_commit_free` when no 29 * longer needed. 30 * 31 * @param commit pointer to the looked up commit 32 * @param repo the repo to use when locating the commit. 33 * @param id identity of the commit to locate. If the object is 34 * an annotated tag it will be peeled back to the commit. 35 * @return 0 or an error code 36 */ 37 //GIT_EXTERN 38 int git_commit_lookup(libgit2_d.types.git_commit** commit, libgit2_d.types.git_repository* repo, const (libgit2_d.oid.git_oid)* id); 39 40 /** 41 * Lookup a commit object from a repository, given a prefix of its 42 * identifier (short id). 43 * 44 * The returned object should be released with `git_commit_free` when no 45 * longer needed. 46 * 47 * @see git_object_lookup_prefix 48 * 49 * @param commit pointer to the looked up commit 50 * @param repo the repo to use when locating the commit. 51 * @param id identity of the commit to locate. If the object is 52 * an annotated tag it will be peeled back to the commit. 53 * @param len the length of the short identifier 54 * @return 0 or an error code 55 */ 56 //GIT_EXTERN 57 int git_commit_lookup_prefix(libgit2_d.types.git_commit** commit, libgit2_d.types.git_repository* repo, const (libgit2_d.oid.git_oid)* id, size_t len); 58 59 /** 60 * Close an open commit 61 * 62 * This is a wrapper around git_object_free() 63 * 64 * IMPORTANT: 65 * It *is* necessary to call this method when you stop 66 * using a commit. Failure to do so will cause a memory leak. 67 * 68 * @param commit the commit to close 69 */ 70 71 //GIT_EXTERN 72 void git_commit_free(libgit2_d.types.git_commit* commit); 73 74 /** 75 * Get the id of a commit. 76 * 77 * @param commit a previously loaded commit. 78 * @return object identity for the commit. 79 */ 80 //GIT_EXTERN 81 const (libgit2_d.oid.git_oid)* git_commit_id(const (libgit2_d.types.git_commit)* commit); 82 83 /** 84 * Get the repository that contains the commit. 85 * 86 * @param commit A previously loaded commit. 87 * @return Repository that contains this commit. 88 */ 89 //GIT_EXTERN 90 libgit2_d.types.git_repository* git_commit_owner(const (libgit2_d.types.git_commit)* commit); 91 92 /** 93 * Get the encoding for the message of a commit, 94 * as a string representing a standard encoding name. 95 * 96 * The encoding may be null if the `encoding` header 97 * in the commit is missing; in that case UTF-8 is assumed. 98 * 99 * @param commit a previously loaded commit. 100 * @return null, or the encoding 101 */ 102 //GIT_EXTERN 103 const (char)* git_commit_message_encoding(const (libgit2_d.types.git_commit)* commit); 104 105 /** 106 * Get the full message of a commit. 107 * 108 * The returned message will be slightly prettified by removing any 109 * potential leading newlines. 110 * 111 * @param commit a previously loaded commit. 112 * @return the message of a commit 113 */ 114 //GIT_EXTERN 115 const (char)* git_commit_message(const (libgit2_d.types.git_commit)* commit); 116 117 /** 118 * Get the full raw message of a commit. 119 * 120 * @param commit a previously loaded commit. 121 * @return the raw message of a commit 122 */ 123 //GIT_EXTERN 124 const (char)* git_commit_message_raw(const (libgit2_d.types.git_commit)* commit); 125 126 /** 127 * Get the short "summary" of the git commit message. 128 * 129 * The returned message is the summary of the commit, comprising the 130 * first paragraph of the message with whitespace trimmed and squashed. 131 * 132 * @param commit a previously loaded commit. 133 * @return the summary of a commit or null on error 134 */ 135 //GIT_EXTERN 136 const (char)* git_commit_summary(libgit2_d.types.git_commit* commit); 137 138 /** 139 * Get the long "body" of the git commit message. 140 * 141 * The returned message is the body of the commit, comprising 142 * everything but the first paragraph of the message. Leading and 143 * trailing whitespaces are trimmed. 144 * 145 * @param commit a previously loaded commit. 146 * @return the body of a commit or null when no the message only 147 * consists of a summary 148 */ 149 //GIT_EXTERN 150 const (char)* git_commit_body(libgit2_d.types.git_commit* commit); 151 152 /** 153 * Get the commit time (i.e. committer time) of a commit. 154 * 155 * @param commit a previously loaded commit. 156 * @return the time of a commit 157 */ 158 //GIT_EXTERN 159 libgit2_d.types.git_time_t git_commit_time(const (libgit2_d.types.git_commit)* commit); 160 161 /** 162 * Get the commit timezone offset (i.e. committer's preferred timezone) of a 163 * commit. 164 * 165 * @param commit a previously loaded commit. 166 * @return positive or negative timezone offset, in minutes from UTC 167 */ 168 //GIT_EXTERN 169 int git_commit_time_offset(const (libgit2_d.types.git_commit)* commit); 170 171 /** 172 * Get the committer of a commit. 173 * 174 * @param commit a previously loaded commit. 175 * @return the committer of a commit 176 */ 177 //GIT_EXTERN 178 const (libgit2_d.types.git_signature)* git_commit_committer(const (libgit2_d.types.git_commit)* commit); 179 180 /** 181 * Get the author of a commit. 182 * 183 * @param commit a previously loaded commit. 184 * @return the author of a commit 185 */ 186 //GIT_EXTERN 187 const (libgit2_d.types.git_signature)* git_commit_author(const (libgit2_d.types.git_commit)* commit); 188 189 /** 190 * Get the committer 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 201 int git_commit_committer_with_mailmap(libgit2_d.types.git_signature** out_, const (libgit2_d.types.git_commit)* commit, const (libgit2_d.types.git_mailmap)* mailmap); 202 203 /** 204 * Get the author of a commit, using the mailmap to map names and email 205 * addresses to canonical real names and email addresses. 206 * 207 * Call `git_signature_free` to free the signature. 208 * 209 * @param out_ a pointer to store the resolved signature. 210 * @param commit a previously loaded commit. 211 * @param mailmap the mailmap to resolve with. (may be NULL) 212 * @return 0 or an error code 213 */ 214 //GIT_EXTERN 215 int git_commit_author_with_mailmap(libgit2_d.types.git_signature** out_, const (libgit2_d.types.git_commit)* commit, const (libgit2_d.types.git_mailmap)* mailmap); 216 217 /** 218 * Get the full raw text of the commit header. 219 * 220 * @param commit a previously loaded commit 221 * @return the header text of the commit 222 */ 223 //GIT_EXTERN 224 const (char)* git_commit_raw_header(const (libgit2_d.types.git_commit)* commit); 225 226 /** 227 * Get the tree pointed to by a commit. 228 * 229 * @param tree_out pointer where to store the tree object 230 * @param commit a previously loaded commit. 231 * @return 0 or an error code 232 */ 233 //GIT_EXTERN 234 int git_commit_tree(libgit2_d.types.git_tree** tree_out, const (libgit2_d.types.git_commit)* commit); 235 236 /** 237 * Get the id of the tree pointed to by a commit. This differs from 238 * `git_commit_tree` in that no attempts are made to fetch an object 239 * from the ODB. 240 * 241 * @param commit a previously loaded commit. 242 * @return the id of tree pointed to by commit. 243 */ 244 //GIT_EXTERN 245 const (libgit2_d.oid.git_oid)* git_commit_tree_id(const (libgit2_d.types.git_commit)* commit); 246 247 /** 248 * Get the number of parents of this commit 249 * 250 * @param commit a previously loaded commit. 251 * @return integer of count of parents 252 */ 253 //GIT_EXTERN 254 uint git_commit_parentcount(const (libgit2_d.types.git_commit)* commit); 255 256 /** 257 * Get the specified parent of the commit. 258 * 259 * @param out_ Pointer where to store the parent commit 260 * @param commit a previously loaded commit. 261 * @param n the position of the parent (from 0 to `parentcount`) 262 * @return 0 or an error code 263 */ 264 //GIT_EXTERN 265 int git_commit_parent(libgit2_d.types.git_commit** out_, const (libgit2_d.types.git_commit)* commit, uint n); 266 267 /** 268 * Get the oid of a specified parent for a commit. This is different from 269 * `git_commit_parent`, which will attempt to load the parent commit from 270 * the ODB. 271 * 272 * @param commit a previously loaded commit. 273 * @param n the position of the parent (from 0 to `parentcount`) 274 * @return the id of the parent, null on error. 275 */ 276 //GIT_EXTERN 277 const (libgit2_d.oid.git_oid)* git_commit_parent_id(const (libgit2_d.types.git_commit)* commit, uint n); 278 279 /** 280 * Get the commit object that is the <n>th generation ancestor 281 * of the named commit object, following only the first parents. 282 * The returned commit has to be freed by the caller. 283 * 284 * Passing `0` as the generation number returns another instance of the 285 * base commit itself. 286 * 287 * @param ancestor Pointer where to store the ancestor commit 288 * @param commit a previously loaded commit. 289 * @param n the requested generation 290 * @return 0 on success; git_error_code.GIT_ENOTFOUND if no matching ancestor exists 291 * or an error code 292 */ 293 //GIT_EXTERN 294 int git_commit_nth_gen_ancestor(libgit2_d.types.git_commit** ancestor, const (libgit2_d.types.git_commit)* commit, uint n); 295 296 /** 297 * Get an arbitrary header field 298 * 299 * @param out_ the buffer to fill; existing content will be 300 * overwritten 301 * @param commit the commit to look in 302 * @param field the header field to return 303 * @return 0 on succeess, git_error_code.GIT_ENOTFOUND if the field does not exist, 304 * or an error code 305 */ 306 //GIT_EXTERN 307 int git_commit_header_field(libgit2_d.buffer.git_buf* out_, const (libgit2_d.types.git_commit)* commit, const (char)* field); 308 309 /** 310 * Extract the signature from a commit 311 * 312 * If the id is not for a commit, the error class will be 313 * `git_error_t.GIT_ERROR_INVALID`. If the commit does not have a signature, the 314 * error class will be `git_error_t.GIT_ERROR_OBJECT`. 315 * 316 * @param signature the signature block; existing content will be 317 * overwritten 318 * @param signed_data signed data; this is the commit contents minus the 319 * signature block; existing content will be overwritten 320 * @param repo the repository in which the commit exists 321 * @param commit_id the commit from which to extract the data 322 * @param field the name of the header field containing the signature 323 * block; pass `null` to extract the default 'gpgsig' 324 * @return 0 on success, git_error_code.GIT_ENOTFOUND if the id is not for a commit 325 * or the commit does not have a signature. 326 */ 327 //GIT_EXTERN 328 int git_commit_extract_signature(libgit2_d.buffer.git_buf* signature, libgit2_d.buffer.git_buf* signed_data, libgit2_d.types.git_repository* repo, libgit2_d.oid.git_oid* commit_id, const (char)* field); 329 330 /** 331 * Create new commit in the repository from a list of `git_object` pointers 332 * 333 * The message will **not** be cleaned up automatically. You can do that 334 * with the `git_message_prettify()` function. 335 * 336 * @param id Pointer in which to store the OID of the newly created commit 337 * 338 * @param repo Repository where to store the commit 339 * 340 * @param update_ref If not null, name of the reference that 341 * will be updated to point to this commit. If the reference 342 * is not direct, it will be resolved to a direct reference. 343 * Use "HEAD" to update the HEAD of the current branch and 344 * make it point to this commit. If the reference doesn't 345 * exist yet, it will be created. If it does exist, the first 346 * parent must be the tip of this branch. 347 * 348 * @param author Signature with author and author time of commit 349 * 350 * @param committer Signature with committer and * commit time of commit 351 * 352 * @param message_encoding The encoding for the message in the 353 * commit, represented with a standard encoding name. 354 * E.g. "UTF-8". If null, no encoding header is written and 355 * UTF-8 is assumed. 356 * 357 * @param message Full message for this commit 358 * 359 * @param tree An instance of a `git_tree` object that will 360 * be used as the tree for the commit. This tree object must 361 * also be owned by the given `repo`. 362 * 363 * @param parent_count Number of parents for this commit 364 * 365 * @param parents Array of `parent_count` pointers to `git_commit` 366 * objects that will be used as the parents for this commit. This 367 * array may be null if `parent_count` is 0 (root commit). All the 368 * given commits must be owned by the `repo`. 369 * 370 * @return 0 or an error code 371 * The created commit will be written to the Object Database and 372 * the given reference will be updated to point to it 373 */ 374 //GIT_EXTERN 375 int git_commit_create(libgit2_d.oid.git_oid* id, libgit2_d.types.git_repository* repo, const (char)* update_ref, const (libgit2_d.types.git_signature)* author, const (libgit2_d.types.git_signature)* committer, const (char)* message_encoding, const (char)* message, const (libgit2_d.types.git_tree)* tree, size_t parent_count, const (libgit2_d.types.git_commit)** parents); 376 377 /** 378 * Create new commit in the repository using a variable argument list. 379 * 380 * The message will **not** be cleaned up automatically. You can do that 381 * with the `git_message_prettify()` function. 382 * 383 * The parents for the commit are specified as a variable list of pointers 384 * to `const git_commit *`. Note that this is a convenience method which may 385 * not be safe to export for certain languages or compilers 386 * 387 * All other parameters remain the same as `git_commit_create()`. 388 * 389 * @see git_commit_create 390 */ 391 //GIT_EXTERN 392 int git_commit_create_v(libgit2_d.oid.git_oid* id, libgit2_d.types.git_repository* repo, const (char)* update_ref, const (libgit2_d.types.git_signature)* author, const (libgit2_d.types.git_signature)* committer, const (char)* message_encoding, const (char)* message, const (libgit2_d.types.git_tree)* tree, size_t parent_count, ...); 393 394 /** 395 * Amend an existing commit by replacing only non-null values. 396 * 397 * This creates a new commit that is exactly the same as the old commit, 398 * except that any non-null values will be updated. The new commit has 399 * the same parents as the old commit. 400 * 401 * The `update_ref` value works as in the regular `git_commit_create()`, 402 * updating the ref to point to the newly rewritten commit. If you want 403 * to amend a commit that is not currently the tip of the branch and then 404 * rewrite the following commits to reach a ref, pass this as null and 405 * update the rest of the commit chain and ref separately. 406 * 407 * Unlike `git_commit_create()`, the `author`, `committer`, `message`, 408 * `message_encoding`, and `tree` parameters can be null in which case this 409 * will use the values from the original `commit_to_amend`. 410 * 411 * All parameters have the same meanings as in `git_commit_create()`. 412 * 413 * @see git_commit_create 414 */ 415 //GIT_EXTERN 416 int git_commit_amend(libgit2_d.oid.git_oid* id, const (libgit2_d.types.git_commit)* commit_to_amend, const (char)* update_ref, const (libgit2_d.types.git_signature)* author, const (libgit2_d.types.git_signature)* committer, const (char)* message_encoding, const (char)* message, const (libgit2_d.types.git_tree)* tree); 417 418 /** 419 * Create a commit and write it into a buffer 420 * 421 * Create a commit as with `git_commit_create()` but instead of 422 * writing it to the objectdb, write the contents of the object into a 423 * buffer. 424 * 425 * @param out_ the buffer into which to write the commit object content 426 * 427 * @param repo Repository where the referenced tree and parents live 428 * 429 * @param author Signature with author and author time of commit 430 * 431 * @param committer Signature with committer and * commit time of commit 432 * 433 * @param message_encoding The encoding for the message in the 434 * commit, represented with a standard encoding name. 435 * E.g. "UTF-8". If null, no encoding header is written and 436 * UTF-8 is assumed. 437 * 438 * @param message Full message for this commit 439 * 440 * @param tree An instance of a `git_tree` object that will 441 * be used as the tree for the commit. This tree object must 442 * also be owned by the given `repo`. 443 * 444 * @param parent_count Number of parents for this commit 445 * 446 * @param parents Array of `parent_count` pointers to `git_commit` 447 * objects that will be used as the parents for this commit. This 448 * array may be null if `parent_count` is 0 (root commit). All the 449 * given commits must be owned by the `repo`. 450 * 451 * @return 0 or an error code 452 */ 453 //GIT_EXTERN 454 int git_commit_create_buffer(libgit2_d.buffer.git_buf* out_, libgit2_d.types.git_repository* repo, const (libgit2_d.types.git_signature)* author, const (libgit2_d.types.git_signature)* committer, const (char)* message_encoding, const (char)* message, const (libgit2_d.types.git_tree)* tree, size_t parent_count, const (libgit2_d.types.git_commit)** parents); 455 456 /** 457 * Create a commit object from the given buffer and signature 458 * 459 * Given the unsigned commit object's contents, its signature and the 460 * header field in which to store the signature, attach the signature 461 * to the commit and write it into the given repository. 462 * 463 * @param out_ the resulting commit id 464 * @param commit_content the content of the unsigned commit object 465 * @param signature the signature to add to the commit. Leave `NULL` 466 * to create a commit without adding a signature field. 467 * @param signature_field which header field should contain this 468 * signature. Leave `NULL` for the default of "gpgsig" 469 * @return 0 or an error code 470 */ 471 //GIT_EXTERN 472 int git_commit_create_with_signature(libgit2_d.oid.git_oid* out_, libgit2_d.types.git_repository* repo, const (char)* commit_content, const (char)* signature, const (char)* signature_field); 473 474 /** 475 * Create an in-memory copy of a commit. The copy must be explicitly 476 * free'd or it will leak. 477 * 478 * @param out_ Pointer to store the copy of the commit 479 * @param source Original commit to copy 480 */ 481 //GIT_EXTERN 482 int git_commit_dup(libgit2_d.types.git_commit** out_, libgit2_d.types.git_commit* source); 483 484 /** 485 * Commit signing callback. 486 * 487 * The callback will be called with the commit content, giving a user an 488 * opportunity to sign the commit content. The signature_field 489 * buf may be left empty to specify the default field "gpgsig". 490 * 491 * Signatures can take the form of any string, and can be created on an arbitrary 492 * header field. Signatures are most commonly used for verifying authorship of a 493 * commit using GPG or a similar cryptographically secure signing algorithm. 494 * See https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work for more 495 * details. 496 * 497 * When the callback: 498 * - returns git_error_code.GIT_PASSTHROUGH, no signature will be added to the commit. 499 * - returns < 0, commit creation will be aborted. 500 * - returns git_error_code.GIT_OK, the signature parameter is expected to be filled. 501 */ 502 alias git_commit_signing_cb = int function(libgit2_d.buffer.git_buf* signature, libgit2_d.buffer.git_buf* signature_field, const (char)* commit_content, void* payload); 503 504 /** @} */