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