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  * @param commit pointer to the looked up commit
  28  * @param repo the repo to use when locating the commit.
  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.
  31  * @return 0 or an error code
  32  */
  33 GIT_EXTERN(int) git_commit_lookup(git_commit **commit, git_repository *repo, const git_oid *id);
  34
  35 /**
  36  * Lookup a commit object from a repository,
  37  * given a prefix of its identifier (short id).
  38  *
  39  * @see git_object_lookup_prefix
  40  *
  41  * @param commit pointer to the looked up commit
  42  * @param repo the repo to use when locating the commit.
  43  * @param id identity of the commit to locate. If the object is
  44  *              an annotated tag it will be peeled back to the commit.
  45  * @param len the length of the short identifier
  46  * @return 0 or an error code
  47  */
  48 GIT_EXTERN(int) git_commit_lookup_prefix(git_commit **commit, git_repository *repo, const git_oid *id, size_t len);
  49
  50 /**
  51  * Close an open commit
  52  *
  53  * This is a wrapper around git_object_free()
  54  *
  55  * IMPORTANT:
  56  * It *is* necessary to call this method when you stop
  57  * using a commit. Failure to do so will cause a memory leak.
  58  *
  59  * @param commit the commit to close
  60  */
  61
  62 GIT_EXTERN(void) git_commit_free(git_commit *commit);
  63
  64 /**
  65  * Get the id of a commit.
  66  *
  67  * @param commit a previously loaded commit.
  68  * @return object identity for the commit.
  69  */
  70 GIT_EXTERN(const git_oid *) git_commit_id(const git_commit *commit);
  71
  72 /**
  73  * Get the repository that contains the commit.
  74  *
  75  * @param commit A previously loaded commit.
  76  * @return Repository that contains this commit.
  77  */
  78 GIT_EXTERN(git_repository *) git_commit_owner(const git_commit *commit);
  79
  80 /**
  81  * Get the encoding for the message of a commit,
  82  * as a string representing a standard encoding name.
  83  *
  84  * The encoding may be NULL if the `encoding` header
  85  * in the commit is missing; in that case UTF-8 is assumed.
  86  *
  87  * @param commit a previously loaded commit.
  88  * @return NULL, or the encoding
  89  */
  90 GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit);
  91
  92 /**
  93  * Get the full message of a commit.
  94  *
  95  * @param commit a previously loaded commit.
  96  * @return the message of a commit
  97  */
  98 GIT_EXTERN(const char *) git_commit_message(const git_commit *commit);
  99
 100 /**
 101  * Get the commit time (i.e. committer time) of a commit.
 102  *
 103  * @param commit a previously loaded commit.
 104  * @return the time of a commit
 105  */
 106 GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit);
 107
 108 /**
 109  * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit.
 110  *
 111  * @param commit a previously loaded commit.
 112  * @return positive or negative timezone offset, in minutes from UTC
 113  */
 114 GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit);
 115
 116 /**
 117  * Get the committer of a commit.
 118  *
 119  * @param commit a previously loaded commit.
 120  * @return the committer of a commit
 121  */
 122 GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit);
 123
 124 /**
 125  * Get the author of a commit.
 126  *
 127  * @param commit a previously loaded commit.
 128  * @return the author of a commit
 129  */
 130 GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit);
 131
 132 /**
 133  * Get the tree pointed to by a commit.
 134  *
 135  * @param tree_out pointer where to store the tree object
 136  * @param commit a previously loaded commit.
 137  * @return 0 or an error code
 138  */
 139 GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit);
 140
 141 /**
 142  * Get the id of the tree pointed to by a commit. This differs from
 143  * `git_commit_tree` in that no attempts are made to fetch an object
 144  * from the ODB.
 145  *
 146  * @param commit a previously loaded commit.
 147  * @return the id of tree pointed to by commit.
 148  */
 149 GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit);
 150
 151 /**
 152  * Get the number of parents of this commit
 153  *
 154  * @param commit a previously loaded commit.
 155  * @return integer of count of parents
 156  */
 157 GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit);
 158
 159 /**
 160  * Get the specified parent of the commit.
 161  *
 162  * @param out Pointer where to store the parent commit
 163  * @param commit a previously loaded commit.
 164  * @param n the position of the parent (from 0 to `parentcount`)
 165  * @return 0 or an error code
 166  */
 167 GIT_EXTERN(int) git_commit_parent(
 168         git_commit **out,
 169         const git_commit *commit,
 170         unsigned int n);
 171
 172 /**
 173  * Get the oid of a specified parent for a commit. This is different from
 174  * `git_commit_parent`, which will attempt to load the parent commit from
 175  * the ODB.
 176  *
 177  * @param commit a previously loaded commit.
 178  * @param n the position of the parent (from 0 to `parentcount`)
 179  * @return the id of the parent, NULL on error.
 180  */
 181 GIT_EXTERN(const git_oid *) git_commit_parent_id(
 182         const git_commit *commit,
 183         unsigned int n);
 184
 185 /**
 186  * Get the commit object that is the <n>th generation ancestor
 187  * of the named commit object, following only the first parents.
 188  * The returned commit has to be freed by the caller.
 189  *
 190  * Passing `0` as the generation number returns another instance of the
 191  * base commit itself.
 192  *
 193  * @param ancestor Pointer where to store the ancestor commit
 194  * @param commit a previously loaded commit.
 195  * @param n the requested generation
 196  * @return 0 on success; GIT_ENOTFOUND if no matching ancestor exists
 197  * or an error code
 198  */
 199 GIT_EXTERN(int) git_commit_nth_gen_ancestor(
 200         git_commit **ancestor,
 201         const git_commit *commit,
 202         unsigned int n);
 203
 204 /**
 205  * Create new commit in the repository from a list of `git_object` pointers
 206  *
 207  * The message will not be cleaned up automatically. You can do that with
 208  * the `git_message_prettify()` function.
 209  *
 210  * @param id Pointer in which to store the OID of the newly created commit
 211  *
 212  * @param repo Repository where to store the commit
 213  *
 214  * @param update_ref If not NULL, name of the reference that
 215  *      will be updated to point to this commit. If the reference
 216  *      is not direct, it will be resolved to a direct reference.
 217  *      Use "HEAD" to update the HEAD of the current branch and
 218  *      make it point to this commit. If the reference doesn't
 219  *      exist yet, it will be created.
 220  *
 221  * @param author Signature with author and author time of commit
 222  *
 223  * @param committer Signature with committer and * commit time of commit
 224  *
 225  * @param message_encoding The encoding for the message in the
 226  *  commit, represented with a standard encoding name.
 227  *  E.g. "UTF-8". If NULL, no encoding header is written and
 228  *  UTF-8 is assumed.
 229  *
 230  * @param message Full message for this commit
 231  *
 232  * @param tree An instance of a `git_tree` object that will
 233  *  be used as the tree for the commit. This tree object must
 234  *  also be owned by the given `repo`.
 235  *
 236  * @param parent_count Number of parents for this commit
 237  *
 238  * @param parents Array of `parent_count` pointers to `git_commit`
 239  *  objects that will be used as the parents for this commit. This
 240  *  array may be NULL if `parent_count` is 0 (root commit). All the
 241  *  given commits must be owned by the `repo`.
 242  *
 243  * @return 0 or an error code
 244  *      The created commit will be written to the Object Database and
 245  *      the given reference will be updated to point to it
 246  */
 247 GIT_EXTERN(int) git_commit_create(
 248         git_oid *id,
 249         git_repository *repo,
 250         const char *update_ref,
 251         const git_signature *author,
 252         const git_signature *committer,
 253         const char *message_encoding,
 254         const char *message,
 255         const git_tree *tree,
 256         int parent_count,
 257         const git_commit *parents[]);
 258
 259 /**
 260  * Create new commit in the repository using a variable argument list.
 261  *
 262  * The message will be cleaned up from excess whitespace and it will be made
 263  * sure that the last line ends with a '\n'.
 264  *
 265  * The parents for the commit are specified as a variable list of pointers
 266  * to `const git_commit *`. Note that this is a convenience method which may
 267  * not be safe to export for certain languages or compilers
 268  *
 269  * All other parameters remain the same at `git_commit_create()`.
 270  *
 271  * @see git_commit_create
 272  */
 273 GIT_EXTERN(int) git_commit_create_v(
 274         git_oid *id,
 275         git_repository *repo,
 276         const char *update_ref,
 277         const git_signature *author,
 278         const git_signature *committer,
 279         const char *message_encoding,
 280         const char *message,
 281         const git_tree *tree,
 282         int parent_count,
 283         ...);
 284
 285 /** @} */
 286 GIT_END_DECL
 287 #endif