include/git2/commit.h

   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 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
 183 /**
 184  * Get the tree pointed to by a commit.
 185  *
 186  * @param tree_out pointer where to store the tree object
 187  * @param commit a previously loaded commit.
 188  * @return 0 or an error code
 189  */
 190 GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit);
 191
 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  */
 200 GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit);
 201
 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  */
 208 GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit);
 209
 210 /**
 211  * Get the specified parent of the commit.
 212  *
 213  * @param out Pointer where to store the parent commit
 214  * @param commit a previously loaded commit.
 215  * @param n the position of the parent (from 0 to `parentcount`)
 216  * @return 0 or an error code
 217  */
 218 GIT_EXTERN(int) git_commit_parent(
 219         git_commit **out,
 220         const git_commit *commit,
 221         unsigned int n);
 222
 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  */
 232 GIT_EXTERN(const git_oid *) git_commit_parent_id(
 233         const git_commit *commit,
 234         unsigned int n);
 235
 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  */
 250 GIT_EXTERN(int) git_commit_nth_gen_ancestor(
 251         git_commit **ancestor,
 252         const git_commit *commit,
 253         unsigned int n);
 254
 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
 266 /**
 267  * Extract the signature from a commit
 268  *
 269  * If the id is not for a commit, the error class will be
 270  * `GITERR_INVALID`. If the commit does not have a signature, the
 271  * error class will be `GITERR_OBJECT`.
 272  *
 273  * @param signature the signature block
 274  * @param signed_data signed data; this is the commit contents minus the signature block
 275  * @param repo the repository in which the commit exists
 276  * @param commit_id the commit from which to extract the data
 277  * @param field the name of the header field containing the signature
 278  * block; pass `NULL` to extract the default 'gpgsig'
 279  * @return 0 on success, GIT_ENOTFOUND if the id is not for a commit
 280  * or the commit does not have a signature.
 281  */
 282 GIT_EXTERN(int) git_commit_extract_signature(git_buf *signature, git_buf *signed_data, git_repository *repo, git_oid *commit_id, const char *field);
 283
 284 /**
 285  * Create new commit in the repository from a list of `git_object` pointers
 286  *
 287  * The message will **not** be cleaned up automatically. You can do that
 288  * with the `git_message_prettify()` function.
 289  *
 290  * @param id Pointer in which to store the OID of the newly created commit
 291  *
 292  * @param repo Repository where to store the commit
 293  *
 294  * @param update_ref If not NULL, name of the reference that
 295  *      will be updated to point to this commit. If the reference
 296  *      is not direct, it will be resolved to a direct reference.
 297  *      Use "HEAD" to update the HEAD of the current branch and
 298  *      make it point to this commit. If the reference doesn't
 299  *      exist yet, it will be created. If it does exist, the first
 300  *      parent must be the tip of this branch.
 301  *
 302  * @param author Signature with author and author time of commit
 303  *
 304  * @param committer Signature with committer and * commit time of commit
 305  *
 306  * @param message_encoding The encoding for the message in the
 307  *  commit, represented with a standard encoding name.
 308  *  E.g. "UTF-8". If NULL, no encoding header is written and
 309  *  UTF-8 is assumed.
 310  *
 311  * @param message Full message for this commit
 312  *
 313  * @param tree An instance of a `git_tree` object that will
 314  *  be used as the tree for the commit. This tree object must
 315  *  also be owned by the given `repo`.
 316  *
 317  * @param parent_count Number of parents for this commit
 318  *
 319  * @param parents Array of `parent_count` pointers to `git_commit`
 320  *  objects that will be used as the parents for this commit. This
 321  *  array may be NULL if `parent_count` is 0 (root commit). All the
 322  *  given commits must be owned by the `repo`.
 323  *
 324  * @return 0 or an error code
 325  *      The created commit will be written to the Object Database and
 326  *      the given reference will be updated to point to it
 327  */
 328 GIT_EXTERN(int) git_commit_create(
 329         git_oid *id,
 330         git_repository *repo,
 331         const char *update_ref,
 332         const git_signature *author,
 333         const git_signature *committer,
 334         const char *message_encoding,
 335         const char *message,
 336         const git_tree *tree,
 337         size_t parent_count,
 338         const git_commit *parents[]);
 339
 340 /**
 341  * Create new commit in the repository using a variable argument list.
 342  *
 343  * The message will **not** be cleaned up automatically. You can do that
 344  * with the `git_message_prettify()` function.
 345  *
 346  * The parents for the commit are specified as a variable list of pointers
 347  * to `const git_commit *`. Note that this is a convenience method which may
 348  * not be safe to export for certain languages or compilers
 349  *
 350  * All other parameters remain the same as `git_commit_create()`.
 351  *
 352  * @see git_commit_create
 353  */
 354 GIT_EXTERN(int) git_commit_create_v(
 355         git_oid *id,
 356         git_repository *repo,
 357         const char *update_ref,
 358         const git_signature *author,
 359         const git_signature *committer,
 360         const char *message_encoding,
 361         const char *message,
 362         const git_tree *tree,
 363         size_t parent_count,
 364         ...);
 365
 366 /**
 367  * Amend an existing commit by replacing only non-NULL values.
 368  *
 369  * This creates a new commit that is exactly the same as the old commit,
 370  * except that any non-NULL values will be updated.  The new commit has
 371  * the same parents as the old commit.
 372  *
 373  * The `update_ref` value works as in the regular `git_commit_create()`,
 374  * updating the ref to point to the newly rewritten commit.  If you want
 375  * to amend a commit that is not currently the tip of the branch and then
 376  * rewrite the following commits to reach a ref, pass this as NULL and
 377  * update the rest of the commit chain and ref separately.
 378  *
 379  * Unlike `git_commit_create()`, the `author`, `committer`, `message`,
 380  * `message_encoding`, and `tree` parameters can be NULL in which case this
 381  * will use the values from the original `commit_to_amend`.
 382  *
 383  * All parameters have the same meanings as in `git_commit_create()`.
 384  *
 385  * @see git_commit_create
 386  */
 387 GIT_EXTERN(int) git_commit_amend(
 388         git_oid *id,
 389         const git_commit *commit_to_amend,
 390         const char *update_ref,
 391         const git_signature *author,
 392         const git_signature *committer,
 393         const char *message_encoding,
 394         const char *message,
 395         const git_tree *tree);
 396
 397 /**
 398  * Create a commit and write it into a buffer
 399  *
 400  * Create a commit as with `git_commit_create()` but instead of
 401  * writing it to the objectdb, write the contents of the object into a
 402  * buffer.
 403  *
 404  * @param out the buffer into which to write the commit object content
 405  *
 406  * @param repo Repository where the referenced tree and parents live
 407  *
 408  * @param author Signature with author and author time of commit
 409  *
 410  * @param committer Signature with committer and * commit time of commit
 411  *
 412  * @param message_encoding The encoding for the message in the
 413  *  commit, represented with a standard encoding name.
 414  *  E.g. "UTF-8". If NULL, no encoding header is written and
 415  *  UTF-8 is assumed.
 416  *
 417  * @param message Full message for this commit
 418  *
 419  * @param tree An instance of a `git_tree` object that will
 420  *  be used as the tree for the commit. This tree object must
 421  *  also be owned by the given `repo`.
 422  *
 423  * @param parent_count Number of parents for this commit
 424  *
 425  * @param parents Array of `parent_count` pointers to `git_commit`
 426  *  objects that will be used as the parents for this commit. This
 427  *  array may be NULL if `parent_count` is 0 (root commit). All the
 428  *  given commits must be owned by the `repo`.
 429  *
 430  * @return 0 or an error code
 431  */
 432 GIT_EXTERN(int) git_commit_create_buffer(
 433         git_buf *out,
 434         git_repository *repo,
 435         const git_signature *author,
 436         const git_signature *committer,
 437         const char *message_encoding,
 438         const char *message,
 439         const git_tree *tree,
 440         size_t parent_count,
 441         const git_commit *parents[]);
 442
 443 /**
 444  * Create a commit object from the given buffer and signature
 445  *
 446  * Given the unsigned commit object's contents, its signature and the
 447  * header field in which to store the signature, attach the signature
 448  * to the commit and write it into the given repository.
 449  *
 450  * @param out the resulting commit id
 451  * @param commit_content the content of the unsigned commit object
 452  * @param signature the signature to add to the commit
 453  * @param signature_field which header field should contain this
 454  * signature. Leave `NULL` for the default of "gpgsig"
 455  * @return 0 or an error code
 456  */
 457 GIT_EXTERN(int) git_commit_create_with_signature(
 458         git_oid *out,
 459         git_repository *repo,
 460         const char *commit_content,
 461         const char *signature,
 462         const char *signature_field);
 463
 464 /**
 465  * Create an in-memory copy of a commit. The copy must be explicitly
 466  * free'd or it will leak.
 467  *
 468  * @param out Pointer to store the copy of the commit
 469  * @param source Original commit to copy
 470  */
 471 GIT_EXTERN(int) git_commit_dup(git_commit **out, git_commit *source);
 472
 473 /** @} */
 474 GIT_END_DECL
 475 #endif