Merge pull request #6016 from libgit2/ethomson/commit_create_cb

Introduce `create_commit_cb`, deprecate `signing_cb`

3 files changed, 81 insertions, 20 deletions

diff --git a/include/git2/commit.h b/include/git2/commit.h
index e6c4656a9..4d74b8994 100644
--- a/include/git2/commit.h
+++ b/include/git2/commit.h
@@ -503,25 +503,41 @@ GIT_EXTERN(int) git_commit_create_with_signature(
 GIT_EXTERN(int) git_commit_dup(git_commit **out, git_commit *source);
 
 /**
- * Commit signing callback.
- *
- * The callback will be called with the commit content, giving a user an
- * opportunity to sign the commit content. The signature_field
- * buf may be left empty to specify the default field "gpgsig".
- *
- * Signatures can take the form of any string, and can be created on an arbitrary
- * header field. Signatures are most commonly used for verifying authorship of a
- * commit using GPG or a similar cryptographically secure signing algorithm.
- * See https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work for more
- * details.
- *
- * When the callback:
- * - returns GIT_PASSTHROUGH, no signature will be added to the commit.
- * - returns < 0, commit creation will be aborted.
- * - returns GIT_OK, the signature parameter is expected to be filled.
- */
-typedef int (*git_commit_signing_cb)(
-	git_buf *signature, git_buf *signature_field, const char *commit_content, void *payload);
+ * Commit creation callback: used when a function is going to create
+ * commits (for example, in `git_rebase_commit`) to allow callers to
+ * override the commit creation behavior.  For example, users may
+ * wish to sign commits by providing this information to
+ * `git_commit_create_buffer`, signing that buffer, then calling
+ * `git_commit_create_with_signature`.  The resultant commit id
+ * should be set in the `out` object id parameter.
+ *
+ * @param out pointer that this callback will populate with the object
+ *            id of the commit that is created
+ * @param author the author name and time of the commit
+ * @param committer the committer name and time of the commit
+ * @param message_encoding the encoding of the given message, or NULL
+ *                         to assume UTF8
+ * @param message the commit message
+ * @param tree the tree to be committed
+ * @param parent_count the number of parents for this commit
+ * @param parents the commit parents
+ * @param payload the payload pointer in the rebase options
+ * @return 0 if this callback has created the commit and populated the out
+ *         parameter, GIT_PASSTHROUGH if the callback has not created a
+ *         commit and wants the calling function to create the commit as
+ *         if no callback had been specified, any other value to stop
+ *         and return a failure
+ */
+typedef int (*git_commit_create_cb)(
+	git_oid *out,
+	const git_signature *author,
+	const git_signature *committer,
+	const char *message_encoding,
+	const char *message,
+	const git_tree *tree,
+	size_t parent_count,
+	const git_commit *parents[],
+	void *payload);
 
 /** @} */
 GIT_END_DECL
diff --git a/include/git2/deprecated.h b/include/git2/deprecated.h
index ac60488ac..611848e10 100644
--- a/include/git2/deprecated.h
+++ b/include/git2/deprecated.h
@@ -205,6 +205,27 @@ GIT_EXTERN(void) git_buf_free(git_buf *buffer);
 
 /**@}*/
 
+/** @name Deprecated Commit Definitions
+ */
+/**@{*/
+
+/**
+ * Provide a commit signature during commit creation.
+ *
+ * Callers should instead define a `git_commit_create_cb` that
+ * generates a commit buffer using `git_commit_create_buffer`, sign
+ * that buffer and call `git_commit_create_with_signature`.
+ *
+ * @deprecated use a `git_commit_create_cb` instead
+ */
+typedef int (*git_commit_signing_cb)(
+	git_buf *signature,
+	git_buf *signature_field,
+	const char *commit_content,
+	void *payload);
+
+/**@}*/
+
 /** @name Deprecated Config Functions and Constants
  */
 /**@{*/
diff --git a/include/git2/rebase.h b/include/git2/rebase.h
index 99a02fef9..11e452cbf 100644
--- a/include/git2/rebase.h
+++ b/include/git2/rebase.h
@@ -75,13 +75,37 @@ typedef struct {
 	git_checkout_options checkout_options;
 
 	/**
+	 * Optional callback that allows users to override commit
+	 * creation in `git_rebase_commit`.  If specified, users can
+	 * create their own commit and provide the commit ID, which
+	 * may be useful for signing commits or otherwise customizing
+	 * the commit creation.
+	 *
+	 * If this callback returns `GIT_PASSTHROUGH`, then
+	 * `git_rebase_commit` will continue to create the commit.
+	 */
+	git_commit_create_cb commit_create_cb;
+
+#ifdef GIT_DEPRECATE_HARD
+	void *reserved;
+#else
+	/**
 	 * If provided, this will be called with the commit content, allowing
 	 * a signature to be added to the rebase commit. Can be skipped with
 	 * GIT_PASSTHROUGH. If GIT_PASSTHROUGH is returned, a commit will be made
 	 * without a signature.
+	 *
 	 * This field is only used when performing git_rebase_commit.
+	 *
+	 * This callback is not invoked if a `git_commit_create_cb` is
+	 * specified.
+	 *
+	 * This callback is deprecated; users should provide a
+	 * creation callback as `commit_create_cb` that produces a
+	 * commit buffer, signs it, and commits it.
 	 */
-	git_commit_signing_cb signing_cb;
+	int (*signing_cb)(git_buf *, git_buf *, const char *, void *);
+#endif
 
 	/**
 	 * This will be passed to each of the callbacks in this struct