Merge branch 'development'v0.18.0

1 files changed, 42 insertions, 20 deletions

diff --git a/include/git2/commit.h b/include/git2/commit.h
index a6d9bb0e3..764053eaa 100644
--- a/include/git2/commit.h
+++ b/include/git2/commit.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2012 the libgit2 contributors
+ * Copyright (C) the libgit2 contributors. All rights reserved.
  *
  * This file is part of libgit2, distributed under the GNU GPL v2 with
  * a Linking Exception. For full terms see the included COPYING file.
@@ -48,7 +48,7 @@ GIT_INLINE(int) git_commit_lookup(git_commit **commit, git_repository *repo, con
  * @param len the length of the short identifier
  * @return 0 or an error code
  */
-GIT_INLINE(int) git_commit_lookup_prefix(git_commit **commit, git_repository *repo, const git_oid *id, unsigned len)
+GIT_INLINE(int) git_commit_lookup_prefix(git_commit **commit, git_repository *repo, const git_oid *id, size_t len)
 {
 	return git_object_lookup_prefix((git_object **)commit, repo, id, len, GIT_OBJ_COMMIT);
 }
@@ -76,7 +76,10 @@ GIT_INLINE(void) git_commit_free(git_commit *commit)
  * @param commit a previously loaded commit.
  * @return object identity for the commit.
  */
-GIT_EXTERN(const git_oid *) git_commit_id(git_commit *commit);
+GIT_INLINE(const git_oid *) git_commit_id(const git_commit *commit)
+{
+	return git_object_id((const git_object *)commit);
+}
 
 /**
  * Get the encoding for the message of a commit,
@@ -88,7 +91,7 @@ GIT_EXTERN(const git_oid *) git_commit_id(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return NULL, or the encoding
  */
-GIT_EXTERN(const char *) git_commit_message_encoding(git_commit *commit);
+GIT_EXTERN(const char *) git_commit_message_encoding(const git_commit *commit);
 
 /**
  * Get the full message of a commit.
@@ -96,7 +99,7 @@ GIT_EXTERN(const char *) git_commit_message_encoding(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the message of a commit
  */
-GIT_EXTERN(const char *) git_commit_message(git_commit *commit);
+GIT_EXTERN(const char *) git_commit_message(const git_commit *commit);
 
 /**
  * Get the commit time (i.e. committer time) of a commit.
@@ -104,7 +107,7 @@ GIT_EXTERN(const char *) git_commit_message(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the time of a commit
  */
-GIT_EXTERN(git_time_t) git_commit_time(git_commit *commit);
+GIT_EXTERN(git_time_t) git_commit_time(const git_commit *commit);
 
 /**
  * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit.
@@ -112,7 +115,7 @@ GIT_EXTERN(git_time_t) git_commit_time(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return positive or negative timezone offset, in minutes from UTC
  */
-GIT_EXTERN(int) git_commit_time_offset(git_commit *commit);
+GIT_EXTERN(int) git_commit_time_offset(const git_commit *commit);
 
 /**
  * Get the committer of a commit.
@@ -120,7 +123,7 @@ GIT_EXTERN(int) git_commit_time_offset(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the committer of a commit
  */
-GIT_EXTERN(const git_signature *) git_commit_committer(git_commit *commit);
+GIT_EXTERN(const git_signature *) git_commit_committer(const git_commit *commit);
 
 /**
  * Get the author of a commit.
@@ -128,7 +131,7 @@ GIT_EXTERN(const git_signature *) git_commit_committer(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the author of a commit
  */
-GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit);
+GIT_EXTERN(const git_signature *) git_commit_author(const git_commit *commit);
 
 /**
  * Get the tree pointed to by a commit.
@@ -137,7 +140,7 @@ GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit);
+GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, const git_commit *commit);
 
 /**
  * Get the id of the tree pointed to by a commit. This differs from
@@ -147,7 +150,7 @@ GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit);
  * @param commit a previously loaded commit.
  * @return the id of tree pointed to by commit.
  */
-GIT_EXTERN(const git_oid *) git_commit_tree_oid(git_commit *commit);
+GIT_EXTERN(const git_oid *) git_commit_tree_id(const git_commit *commit);
 
 /**
  * Get the number of parents of this commit
@@ -155,17 +158,17 @@ GIT_EXTERN(const git_oid *) git_commit_tree_oid(git_commit *commit);
  * @param commit a previously loaded commit.
  * @return integer of count of parents
  */
-GIT_EXTERN(unsigned int) git_commit_parentcount(git_commit *commit);
+GIT_EXTERN(unsigned int) git_commit_parentcount(const git_commit *commit);
 
 /**
  * Get the specified parent of the commit.
  *
- * @param parent Pointer where to store the parent commit
+ * @param out Pointer where to store the parent commit
  * @param commit a previously loaded commit.
  * @param n the position of the parent (from 0 to `parentcount`)
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsigned int n);
+GIT_EXTERN(int) git_commit_parent(git_commit **out, git_commit *commit, unsigned int n);
 
 /**
  * Get the oid of a specified parent for a commit. This is different from
@@ -176,16 +179,35 @@ GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsig
  * @param n the position of the parent (from 0 to `parentcount`)
  * @return the id of the parent, NULL on error.
  */
-GIT_EXTERN(const git_oid *) git_commit_parent_oid(git_commit *commit, unsigned int n);
+GIT_EXTERN(const git_oid *) git_commit_parent_id(git_commit *commit, unsigned int n);
+
+/**
+ * Get the commit object that is the <n>th generation ancestor
+ * of the named commit object, following only the first parents.
+ * The returned commit has to be freed by the caller.
+ *
+ * Passing `0` as the generation number returns another instance of the
+ * base commit itself.
+ *
+ * @param ancestor Pointer where to store the ancestor commit
+ * @param commit a previously loaded commit.
+ * @param n the requested generation
+ * @return 0 on success; GIT_ENOTFOUND if no matching ancestor exists
+ * or an error code
+ */
+GIT_EXTERN(int) git_commit_nth_gen_ancestor(
+	git_commit **ancestor,
+	const git_commit *commit,
+	unsigned int n);
 
 /**
  * Create a new commit in the repository using `git_object`
  * instances as parameters.
  *
- * The message will be cleaned up from excess whitespace
- * it will be made sure that the last line ends with a '\n'.
+ * The message will not be cleaned up. This can be achieved
+ * through `git_message_prettify()`.
  *
- * @param oid Pointer where to store the OID of the
+ * @param id Pointer where to store the OID of the
  *	newly created commit
  *
  * @param repo Repository where to store the commit
@@ -226,7 +248,7 @@ GIT_EXTERN(const git_oid *) git_commit_parent_oid(git_commit *commit, unsigned i
  *	the given reference will be updated to point to it
  */
 GIT_EXTERN(int) git_commit_create(
-		git_oid *oid,
+		git_oid *id,
 		git_repository *repo,
 		const char *update_ref,
 		const git_signature *author,
@@ -254,7 +276,7 @@ GIT_EXTERN(int) git_commit_create(
  * @see git_commit_create
  */
 GIT_EXTERN(int) git_commit_create_v(
-		git_oid *oid,
+		git_oid *id,
 		git_repository *repo,
 		const char *update_ref,
 		const git_signature *author,