commit.h in rugged-0.28.4

- old
+ new

@@ -478,11 +478,12 @@
  * header field in which to store the signature, attach the signature
  * to the commit and write it into the given repository.
  *
  * @param out the resulting commit id
  * @param commit_content the content of the unsigned commit object
- * @param signature the signature to add to the commit
+ * @param signature the signature to add to the commit. Leave `NULL`
+ * to create a commit without adding a signature field.
  * @param signature_field which header field should contain this
  * signature. Leave `NULL` for the default of "gpgsig"
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_commit_create_with_signature(
@@ -498,9 +499,30 @@
  *
  * @param out Pointer to store the copy of the commit
  * @param source Original commit to copy
  */
 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);
 
 /** @} */
 GIT_END_DECL
 #endif