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  * @param commit a previously loaded commit.
 104  * @return the message of a commit
 105  */
 106 GIT_EXTERN(const char *) git_commit_message(const git_commit *commit);
 107
 108 /**
 109  * Get the commit time (i.e. committer time) of a commit.
 110  *
 111  * @param commit a previously loaded commit.
 112  * @return the time of a commit
 113  */
 114 GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit);
 115
 116 /**
 117  * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit.
 118  *
 119  * @param commit a previously loaded commit.
 120  * @return positive or negative timezone offset, in minutes from UTC
 121  */
 122 GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit);
 123
 124 /**
 125  * Get the committer of a commit.
 126  *
 127  * @param commit a previously loaded commit.
 128  * @return the committer of a commit
 129  */
 130 GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit);
 131
 132 /**
 133  * Get the author of a commit.
 134  *
 135  * @param commit a previously loaded commit.
 136  * @return the author of a commit
 137  */
 138 GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit);
 139
 140 /**
 141  * Get the full raw text of the commit header.
 142  *
 143  * @param commit a previously loaded commit
 144  * @return the header text of the commit
 145  */
 146 GIT_EXTERN(const char *) git_commit_raw_header(const git_commit *commit);
 147
 148 /**
 149  * Get the tree pointed to by a commit.
 150  *
 151  * @param tree_out pointer where to store the tree object
 152  * @param commit a previously loaded commit.
 153  * @return 0 or an error code
 154  */
 155 GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit);
 156
 157 /**
 158  * Get the id of the tree pointed to by a commit. This differs from
 159  * `git_commit_tree` in that no attempts are made to fetch an object
 160  * from the ODB.
 161  *
 162  * @param commit a previously loaded commit.
 163  * @return the id of tree pointed to by commit.
 164  */
 165 GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit);
 166
 167 /**
 168  * Get the number of parents of this commit
 169  *
 170  * @param commit a previously loaded commit.
 171  * @return integer of count of parents
 172  */
 173 GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit);
 174
 175 /**
 176  * Get the specified parent of the commit.
 177  *
 178  * @param out Pointer where to store the parent commit
 179  * @param commit a previously loaded commit.
 180  * @param n the position of the parent (from 0 to `parentcount`)
 181  * @return 0 or an error code
 182  */
 183 GIT_EXTERN(int) git_commit_parent(
 184         git_commit **out,
 185         const git_commit *commit,
 186         unsigned int n);
 187
 188 /**
 189  * Get the oid of a specified parent for a commit. This is different from
 190  * `git_commit_parent`, which will attempt to load the parent commit from
 191  * the ODB.
 192  *
 193  * @param commit a previously loaded commit.
 194  * @param n the position of the parent (from 0 to `parentcount`)
 195  * @return the id of the parent, NULL on error.
 196  */
 197 GIT_EXTERN(const git_oid *) git_commit_parent_id(
 198         const git_commit *commit,
 199         unsigned int n);
 200
 201 /**
 202  * Get the commit object that is the <n>th generation ancestor
 203  * of the named commit object, following only the first parents.
 204  * The returned commit has to be freed by the caller.
 205  *
 206  * Passing `0` as the generation number returns another instance of the
 207  * base commit itself.
 208  *
 209  * @param ancestor Pointer where to store the ancestor commit
 210  * @param commit a previously loaded commit.
 211  * @param n the requested generation
 212  * @return 0 on success; GIT_ENOTFOUND if no matching ancestor exists
 213  * or an error code
 214  */
 215 GIT_EXTERN(int) git_commit_nth_gen_ancestor(
 216         git_commit **ancestor,
 217         const git_commit *commit,
 218         unsigned int n);
 219
 220 /**
 221  * Create new commit in the repository from a list of `git_object` pointers
 222  *
 223  * The message will not be cleaned up automatically. You can do that with
 224  * the `git_message_prettify()` function.
 225  *
 226  * @param id Pointer in which to store the OID of the newly created commit
 227  *
 228  * @param repo Repository where to store the commit
 229  *
 230  * @param update_ref If not NULL, name of the reference that
 231  *      will be updated to point to this commit. If the reference
 232  *      is not direct, it will be resolved to a direct reference.
 233  *      Use "HEAD" to update the HEAD of the current branch and
 234  *      make it point to this commit. If the reference doesn't
 235  *      exist yet, it will be created.
 236  *
 237  * @param author Signature with author and author time of commit
 238  *
 239  * @param committer Signature with committer and * commit time of commit
 240  *
 241  * @param message_encoding The encoding for the message in the
 242  *  commit, represented with a standard encoding name.
 243  *  E.g. "UTF-8". If NULL, no encoding header is written and
 244  *  UTF-8 is assumed.
 245  *
 246  * @param message Full message for this commit
 247  *
 248  * @param tree An instance of a `git_tree` object that will
 249  *  be used as the tree for the commit. This tree object must
 250  *  also be owned by the given `repo`.
 251  *
 252  * @param parent_count Number of parents for this commit
 253  *
 254  * @param parents Array of `parent_count` pointers to `git_commit`
 255  *  objects that will be used as the parents for this commit. This
 256  *  array may be NULL if `parent_count` is 0 (root commit). All the
 257  *  given commits must be owned by the `repo`.
 258  *
 259  * @return 0 or an error code
 260  *      The created commit will be written to the Object Database and
 261  *      the given reference will be updated to point to it
 262  */
 263 GIT_EXTERN(int) git_commit_create(
 264         git_oid *id,
 265         git_repository *repo,
 266         const char *update_ref,
 267         const git_signature *author,
 268         const git_signature *committer,
 269         const char *message_encoding,
 270         const char *message,
 271         const git_tree *tree,
 272         int parent_count,
 273         const git_commit *parents[]);
 274
 275 /**
 276  * Create new commit in the repository using a variable argument list.
 277  *
 278  * The message will be cleaned up from excess whitespace and it will be made
 279  * sure that the last line ends with a '\n'.
 280  *
 281  * The parents for the commit are specified as a variable list of pointers
 282  * to `const git_commit *`. Note that this is a convenience method which may
 283  * not be safe to export for certain languages or compilers
 284  *
 285  * All other parameters remain the same at `git_commit_create()`.
 286  *
 287  * @see git_commit_create
 288  */
 289 GIT_EXTERN(int) git_commit_create_v(
 290         git_oid *id,
 291         git_repository *repo,
 292         const char *update_ref,
 293         const git_signature *author,
 294         const git_signature *committer,
 295         const char *message_encoding,
 296         const char *message,
 297         const git_tree *tree,
 298         int parent_count,
 299         ...);
 300
 301 /** @} */
 302 GIT_END_DECL
 303 #endif