email: introduce `git_email_create_from_diff`

Introduce a function to create an email from a diff and multiple inputs
about the source of the diff.

Creating an email from a diff requires many more inputs, and should be
discouraged in favor of building directly from a commit, and is thus in
the `sys` namespace.

2 files changed, 67 insertions, 13 deletions

diff --git a/include/git2/email.h b/include/git2/email.h
index 6014c6c7c..48715fe76 100644
--- a/include/git2/email.h
+++ b/include/git2/email.h
@@ -73,30 +73,39 @@ typedef struct {
 
 /**
  * Create a diff for a commit in mbox format for sending via email.
- * The commit must not be a merge commit.
  *
  * @param out buffer to store the e-mail patch in
- * @param commit commit to create a patch for
+ * @param diff the changes to include in the email
+ * @param patch_idx the patch index
+ * @param patch_count the total number of patches that will be included
+ * @param commit_id the commit id for this change
+ * @param summary the commit message for this change
+ * @param body optional text to include above the diffstat
+ * @param author the person who authored this commit
  * @param opts email creation options
  */
-GIT_EXTERN(int) git_email_create_from_commit(
+GIT_EXTERN(int) git_email_create_from_diff(
 	git_buf *out,
-	git_commit *commit,
+	git_diff *diff,
+	size_t patch_idx,
+	size_t patch_count,
+	const git_oid *commit_id,
+	const char *summary,
+	const char *body,
+	const git_signature *author,
 	const git_email_create_options *opts);
 
 /**
- * Create an mbox format diff for the given commits in the revision
- * spec, excluding merge commits.
+ * Create a diff for a commit in mbox format for sending via email.
+ * The commit must not be a merge commit.
  *
- * @param out buffer to store the e-mail patches in
- * @param commits the array of commits to create patches for
- * @param len the length of the `commits` array
+ * @param out buffer to store the e-mail patch in
+ * @param commit commit to create a patch for
  * @param opts email creation options
  */
-GIT_EXTERN(int) git_email_create_from_commits(
-	git_strarray *out,
-	git_commit **commits,
-	size_t len,
+GIT_EXTERN(int) git_email_create_from_commit(
+	git_buf *out,
+	git_commit *commit,
 	const git_email_create_options *opts);
 
 GIT_END_DECL
diff --git a/include/git2/sys/email.h b/include/git2/sys/email.h
new file mode 100644
index 000000000..6f4a28662
--- /dev/null
+++ b/include/git2/sys/email.h
@@ -0,0 +1,45 @@
+/*
+ * 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.
+ */
+#ifndef INCLUDE_sys_git_email_h__
+#define INCLUDE_sys_git_email_h__
+
+/**
+ * @file git2/sys/email.h
+ * @brief Advanced git email creation routines
+ * @defgroup git_email Advanced git email creation routines
+ * @ingroup Git
+ * @{
+ */
+GIT_BEGIN_DECL
+
+/**
+ * Create a diff for a commit in mbox format for sending via email.
+ *
+ * @param out buffer to store the e-mail patch in
+ * @param diff the changes to include in the email
+ * @param patch_idx the patch index
+ * @param patch_count the total number of patches that will be included
+ * @param commit_id the commit id for this change
+ * @param summary the commit message for this change
+ * @param body optional text to include above the diffstat
+ * @param author the person who authored this commit
+ * @param opts email creation options
+ */
+GIT_EXTERN(int) git_email_create_from_diff(
+	git_buf *out,
+	git_diff *diff,
+	size_t patch_idx,
+	size_t patch_count,
+	const git_oid *commit_id,
+	const char *summary,
+	const char *body,
+	const git_signature *author,
+	const git_email_create_options *opts);
+
+/** @} */
+GIT_END_DECL
+#endif