Merge upstream/development

Signed-off-by: Carlos Martín Nieto <cmn@elego.de>

1 files changed, 137 insertions, 39 deletions

diff --git a/include/git2/commit.h b/include/git2/commit.h
index 21836dbbd..c09b34843 100644
--- a/include/git2/commit.h
+++ b/include/git2/commit.h
@@ -41,8 +41,6 @@ GIT_BEGIN_DECL
 
 /**
  * Lookup a commit object from a repository.
- * The generated commit object is owned by the revision
- * repo and shall not be freed by the user.
  *
  * @param commit pointer to the looked up commit
  * @param repo the repo to use when locating the commit.
@@ -56,23 +54,25 @@ GIT_INLINE(int) git_commit_lookup(git_commit **commit, git_repository *repo, con
 }
 
 /**
- * Create a new in-memory git_commit.
+ * Close an open commit
  *
- * The commit object must be manually filled using
- * setter methods before it can be written to its
- * repository.
+ * This is a wrapper around git_object_close()
  *
- * @param commit pointer to the new commit
- * @param repo The repository where the object will reside
- * @return 0 on success; error code otherwise
+ * IMPORTANT:
+ * It *is* necessary to call this method when you stop
+ * using a commit. Failure to do so will cause a memory leak.
+ *
+ * @param commit the commit to close
  */
-GIT_INLINE(int) git_commit_new(git_commit **commit, git_repository *repo)
+
+GIT_INLINE(void) git_commit_close(git_commit *commit)
 {
-	return git_object_new((git_object **)commit, repo, GIT_OBJ_COMMIT);
+	git_object_close((git_object *) commit);
 }
 
 /**
  * Get the id of a commit.
+ *
  * @param commit a previously loaded commit.
  * @return object identity for the commit.
  */
@@ -80,6 +80,7 @@ GIT_EXTERN(const git_oid *) git_commit_id(git_commit *commit);
 
 /**
  * Get the short (one line) message of a commit.
+ *
  * @param commit a previously loaded commit.
  * @return the short message of a commit
  */
@@ -87,6 +88,7 @@ GIT_EXTERN(const char *) git_commit_message_short(git_commit *commit);
 
 /**
  * Get the full message of a commit.
+ *
  * @param commit a previously loaded commit.
  * @return the message of a commit
  */
@@ -94,13 +96,15 @@ GIT_EXTERN(const char *) git_commit_message(git_commit *commit);
 
 /**
  * Get the commit time (i.e. committer time) of a commit.
+ *
  * @param commit a previously loaded commit.
  * @return the time of a commit
  */
-GIT_EXTERN(time_t) git_commit_time(git_commit *commit);
+GIT_EXTERN(git_time_t) git_commit_time(git_commit *commit);
 
 /**
  * Get the commit timezone offset (i.e. committer's preferred timezone) of a commit.
+ *
  * @param commit a previously loaded commit.
  * @return positive or negative timezone offset, in minutes from UTC
  */
@@ -108,6 +112,7 @@ GIT_EXTERN(int) git_commit_time_offset(git_commit *commit);
 
 /**
  * Get the committer of a commit.
+ *
  * @param commit a previously loaded commit.
  * @return the committer of a commit
  */
@@ -115,6 +120,7 @@ GIT_EXTERN(const git_signature *) git_commit_committer(git_commit *commit);
 
 /**
  * Get the author of a commit.
+ *
  * @param commit a previously loaded commit.
  * @return the author of a commit
  */
@@ -122,10 +128,12 @@ GIT_EXTERN(const git_signature *) git_commit_author(git_commit *commit);
 
 /**
  * Get the tree pointed to by a commit.
+ *
+ * @param tree_out pointer where to store the tree object
  * @param commit a previously loaded commit.
- * @return the tree of a commit
+ * @return 0 on success; error code otherwise
  */
-GIT_EXTERN(const git_tree *) git_commit_tree(git_commit *commit);
+GIT_EXTERN(int) git_commit_tree(git_tree **tree_out, git_commit *commit);
 
 /**
  * Get the number of parents of this commit
@@ -137,47 +145,137 @@ GIT_EXTERN(unsigned int) git_commit_parentcount(git_commit *commit);
 
 /**
  * Get the specified parent of the commit.
+ *
+ * @param parent Pointer where to store the parent commit
  * @param commit a previously loaded commit.
- * @param n the position of the entry
- * @return a pointer to the commit; NULL if out of bounds
+ * @param n the position of the parent (from 0 to `parentcount`)
+ * @return 0 on success; error code otherwise
  */
-GIT_EXTERN(git_commit *) git_commit_parent(git_commit *commit, unsigned int n);
+GIT_EXTERN(int) git_commit_parent(git_commit **parent, git_commit *commit, unsigned int n);
+
 
 /**
- * Add a new parent commit to an existing commit
- * @param commit the commit object
- * @param new_parent the new commit which will be a parent
+ * Create a new commit in the repository
+ *
+ *
+ * @param oid Pointer where to store the OID of the
+ *	newly created commit
+ *
+ * @param repo Repository where to store the commit
+ *
+ * @param update_ref If not NULL, name of the reference that
+ *	will be updated to point to this commit. If the reference
+ *	is not direct, it will be resolved to a direct reference.
+ *	Use "HEAD" to update the HEAD of the current branch and
+ *	make it point to this commit
+ *
+ * @param author Signature representing the author and the authory
+ *	time of this commit
+ *
+ * @param committer Signature representing the committer and the
+ *  commit time of this commit
+ *
+ * @param message Full message for this commit
+ *
+ * @param tree_oid Object ID of the tree for this commit. Note that
+ *  no validation is performed on this OID. Use the _o variants of
+ *  this method to assure a proper tree is passed to the commit.
+ *
+ * @param parent_count Number of parents for this commit
+ *
+ * @param parents Array of pointers to parent OIDs for this commit.
+ *	Note that no validation is performed on these OIDs. Use the _o
+ *	variants of this method to assure that are parents for the commit
+ *	are proper objects.
+ *
  * @return 0 on success; error code otherwise
+ *	The created commit will be written to the Object Database and
+ *	the given reference will be updated to point to it
  */
-GIT_EXTERN(int) git_commit_add_parent(git_commit *commit, git_commit *new_parent);
+GIT_EXTERN(int) git_commit_create(
+		git_oid *oid,
+		git_repository *repo,
+		const char *update_ref,
+		const git_signature *author,
+		const git_signature *committer,
+		const char *message,
+		const git_oid *tree_oid,
+		int parent_count,
+		const git_oid *parent_oids[]);
 
 /**
- * Set the message of a commit
- * @param commit the commit object
- * @param message the new message
+ * Create a new commit in the repository using `git_object`
+ * instances as parameters.
+ *
+ * The `tree_oid` and `parent_oids` paremeters now take a instance
+ * of `git_tree` and `git_commit`, respectively.
+ *
+ * All other parameters remain the same
+ *
+ * @see git_commit_create
  */
-GIT_EXTERN(void) git_commit_set_message(git_commit *commit, const char *message);
+GIT_EXTERN(int) git_commit_create_o(
+		git_oid *oid,
+		git_repository *repo,
+		const char *update_ref,
+		const git_signature *author,
+		const git_signature *committer,
+		const char *message,
+		const git_tree *tree,
+		int parent_count,
+		const git_commit *parents[]);
 
 /**
- * Set the committer of a commit
- * @param commit the commit object
- * @param author_sig signature of the committer
+ * Create a new commit in the repository using `git_object`
+ * instances and a variable argument list.
+ *
+ * The `tree_oid` paremeter now takes a instance
+ * of `const git_tree *`.
+ *
+ * The parents for the commit are specified as a variable
+ * list of pointers to `const git_commit *`. Note that this
+ * is a convenience method which may not be safe to export
+ * for certain languages or compilers
+ *
+ * All other parameters remain the same
+ *
+ * @see git_commit_create
  */
-GIT_EXTERN(void) git_commit_set_committer(git_commit *commit, const git_signature *committer_sig);
+GIT_EXTERN(int) git_commit_create_ov(
+		git_oid *oid,
+		git_repository *repo,
+		const char *update_ref,
+		const git_signature *author,
+		const git_signature *committer,
+		const char *message,
+		const git_tree *tree,
+		int parent_count,
+		...);
 
-/**
- * Set the author of a commit
- * @param commit the commit object
- * @param author_sig signature of the author
- */
-GIT_EXTERN(void) git_commit_set_author(git_commit *commit, const git_signature *author_sig);
 
 /**
- * Set the tree which is pointed to by a commit
- * @param commit the commit object
- * @param tree the new tree
+ * Create a new commit in the repository using 
+ * a variable argument list.
+ *
+ * The parents for the commit are specified as a variable
+ * list of pointers to `const git_oid *`. Note that this
+ * is a convenience method which may not be safe to export
+ * for certain languages or compilers
+ *
+ * All other parameters remain the same
+ *
+ * @see git_commit_create
  */
-GIT_EXTERN(void) git_commit_set_tree(git_commit *commit, git_tree *tree);
+GIT_EXTERN(int) git_commit_create_v(
+		git_oid *oid,
+		git_repository *repo,
+		const char *update_ref,
+		const git_signature *author,
+		const git_signature *committer,
+		const char *message,
+		const git_oid *tree_oid,
+		int parent_count,
+		...);
 
 /** @} */
 GIT_END_DECL