Add git_commit_amend API

This adds an API to amend an existing commit, basically a shorthand
for creating a new commit filling in missing parameters from the
values of an existing commit.  As part of this, I also added a new
"sys" API to create a commit using a callback to get the parents.
This allowed me to rewrite all the other commit creation APIs so
that temporary allocations are no longer needed.

2 files changed, 75 insertions, 10 deletions

diff --git a/include/git2/commit.h b/include/git2/commit.h
index 8b03df0a9..834330b5d 100644
--- a/include/git2/commit.h
+++ b/include/git2/commit.h
@@ -242,8 +242,8 @@ GIT_EXTERN(int) git_commit_nth_gen_ancestor(
 /**
  * Create new commit in the repository from a list of `git_object` pointers
  *
- * The message will not be cleaned up automatically. You can do that with
- * the `git_message_prettify()` function.
+ * The message will **not** be cleaned up automatically. You can do that
+ * with the `git_message_prettify()` function.
  *
  * @param id Pointer in which to store the OID of the newly created commit
  *
@@ -291,20 +291,20 @@ GIT_EXTERN(int) git_commit_create(
 	const char *message_encoding,
 	const char *message,
 	const git_tree *tree,
-	int parent_count,
+	size_t parent_count,
 	const git_commit *parents[]);
 
 /**
  * Create new commit in the repository using a variable argument list.
  *
- * The message will be cleaned up from excess whitespace and it will be made
- * sure that the last line ends with a '\n'.
+ * The message will **not** be cleaned up automatically. You can do that
+ * with the `git_message_prettify()` function.
  *
  * 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 at `git_commit_create()`.
+ * All other parameters remain the same as `git_commit_create()`.
  *
  * @see git_commit_create
  */
@@ -317,9 +317,40 @@ GIT_EXTERN(int) git_commit_create_v(
 	const char *message_encoding,
 	const char *message,
 	const git_tree *tree,
-	int parent_count,
+	size_t parent_count,
 	...);
 
+/**
+ * Amend an existing commit by replacing only non-NULL values.
+ *
+ * This creates a new commit that is exactly the same as the old commit,
+ * except that any non-NULL values will be updated.  The new commit has
+ * the same parents as the old commit.
+ *
+ * The `update_ref` value works as in the regular `git_commit_create()`,
+ * updating the ref to point to the newly rewritten commit.  If you want
+ * to amend a commit that is not currently the HEAD of the branch and then
+ * rewrite the following commits to reach a ref, pass this as NULL and
+ * update the rest of the commit chain and ref separately.
+ *
+ * Unlike `git_commit_create()`, the `author`, `committer`, `message`,
+ * `message_encoding`, and `tree` parameters can be NULL in which case this
+ * will use the values from the original `commit_to_amend`.
+ *
+ * All parameters have the same meanings as in `git_commit_create()`.
+ *
+ * @see git_commit_create
+ */
+GIT_EXTERN(int) git_commit_amend(
+	git_oid *id,
+	const git_commit *commit_to_amend,
+	const char *update_ref,
+	const git_signature *author,
+	const git_signature *committer,
+	const char *message_encoding,
+	const char *message,
+	const git_tree *tree);
+
 /** @} */
 GIT_END_DECL
 #endif
diff --git a/include/git2/sys/commit.h b/include/git2/sys/commit.h
index c8ed56b66..627d3ae2e 100644
--- a/include/git2/sys/commit.h
+++ b/include/git2/sys/commit.h
@@ -21,16 +21,18 @@
 GIT_BEGIN_DECL
 
 /**
- * Create new commit in the repository from a list of `git_oid` values
+ * Create new commit in the repository from a list of `git_oid` values.
  *
  * See documentation for `git_commit_create()` for information about the
  * parameters, as the meaning is identical excepting that `tree` and
  * `parents` now take `git_oid`.  This is a dangerous API in that nor
  * the `tree`, neither the `parents` list of `git_oid`s are checked for
  * validity.
+ *
+ * @see git_commit_create
  */
 GIT_EXTERN(int) git_commit_create_from_ids(
-	git_oid *oid,
+	git_oid *id,
 	git_repository *repo,
 	const char *update_ref,
 	const git_signature *author,
@@ -38,9 +40,41 @@ GIT_EXTERN(int) git_commit_create_from_ids(
 	const char *message_encoding,
 	const char *message,
 	const git_oid *tree,
-	int parent_count,
+	size_t parent_count,
 	const git_oid *parents[]);
 
+/**
+ * Callback function to return parents for commit.
+ *
+ * This is invoked with the count of the number of parents processed so far
+ * along with the user supplied payload.  This should return a git_oid of
+ * the next parent or NULL if all parents have been provided.
+ */
+typedef const git_oid *(*git_commit_parent_callback)(size_t idx, void *payload);
+
+/**
+ * Create a new commit in the repository with an callback to supply parents.
+ *
+ * See documentation for `git_commit_create()` for information about the
+ * parameters, as the meaning is identical excepting that `tree` takes a
+ * `git_oid` and doesn't check for validity, and `parent_cb` is invoked
+ * with `parent_payload` and should return `git_oid` values or NULL to
+ * indicate that all parents are accounted for.
+ *
+ * @see git_commit_create
+ */
+GIT_EXTERN(int) git_commit_create_from_callback(
+	git_oid *id,
+	git_repository *repo,
+	const char *update_ref,
+	const git_signature *author,
+	const git_signature *committer,
+	const char *message_encoding,
+	const char *message,
+	const git_oid *tree,
+	git_commit_parent_callback parent_cb,
+	void *parent_payload);
+
 /** @} */
 GIT_END_DECL
 #endif