diff: deprecate diff_format_email

`git_diff_format_email` is deprecated in favor of `git_email_create`.

include/git2/deprecated.h

@@ -294,6 +294,102 @@ typedef git_configmap git_cvar_map;
 
 /**@}*/
 
+/** @name Deprecated Diff Functions and Constants
+ *
+ * These functions and enumeration values are retained for backward
+ * compatibility.  The newer versions of these functions and values
+ * should be preferred in all new code.
+ *
+ * There is no plan to remove these backward compatibility values at
+ * this time.
+ */
+/**@{*/
+
+/**
+ * Formatting options for diff e-mail generation
+ */
+typedef enum {
+	/** Normal patch, the default */
+	GIT_DIFF_FORMAT_EMAIL_NONE = 0,
+
+	/** Don't insert "[PATCH]" in the subject header*/
+	GIT_DIFF_FORMAT_EMAIL_EXCLUDE_SUBJECT_PATCH_MARKER = (1 << 0),
+
+} git_diff_format_email_flags_t;
+
+/**
+ * Options for controlling the formatting of the generated e-mail.
+ */
+typedef struct {
+	unsigned int version;
+
+	/** see `git_diff_format_email_flags_t` above */
+	uint32_t flags;
+
+	/** This patch number */
+	size_t patch_no;
+
+	/** Total number of patches in this series */
+	size_t total_patches;
+
+	/** id to use for the commit */
+	const git_oid *id;
+
+	/** Summary of the change */
+	const char *summary;
+
+	/** Commit message's body */
+	const char *body;
+
+	/** Author of the change */
+	const git_signature *author;
+} git_diff_format_email_options;
+
+#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION 1
+#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT {GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION, 0, 1, 1, NULL, NULL, NULL, NULL}
+
+/**
+ * Create an e-mail ready patch from a diff.
+ *
+ * @deprecated git_email_create_from_diff
+ * @see git_email_create_from_diff
+ */
+GIT_EXTERN(int) git_diff_format_email(
+	git_buf *out,
+	git_diff *diff,
+	const git_diff_format_email_options *opts);
+
+/**
+ * Create an e-mail ready patch for a commit.
+ *
+ * @deprecated git_email_create_from_commit
+ * @see git_email_create_from_commit
+ */
+GIT_EXTERN(int) git_diff_commit_as_email(
+	git_buf *out,
+	git_repository *repo,
+	git_commit *commit,
+	size_t patch_no,
+	size_t total_patches,
+	uint32_t flags,
+	const git_diff_options *diff_opts);
+
+/**
+ * Initialize git_diff_format_email_options structure
+ *
+ * Initializes a `git_diff_format_email_options` with default values. Equivalent
+ * to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT.
+ *
+ * @param opts The `git_blame_options` struct to initialize.
+ * @param version The struct version; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
+GIT_EXTERN(int) git_diff_format_email_options_init(
+	git_diff_format_email_options *opts,
+	unsigned int version);
+
+/**@}*/
+
 /** @name Deprecated Error Functions and Constants
  *
  * These functions and enumeration values are retained for backward

include/git2/diff.h

@@ -1377,99 +1377,6 @@ GIT_EXTERN(int) git_diff_stats_to_buf(
 GIT_EXTERN(void) git_diff_stats_free(git_diff_stats *stats);
 
 /**
- * Formatting options for diff e-mail generation
- */
-typedef enum {
-	/** Normal patch, the default */
-	GIT_DIFF_FORMAT_EMAIL_NONE = 0,
-
-	/** Don't insert "[PATCH]" in the subject header*/
-	GIT_DIFF_FORMAT_EMAIL_EXCLUDE_SUBJECT_PATCH_MARKER = (1 << 0),
-
-} git_diff_format_email_flags_t;
-
-/**
- * Options for controlling the formatting of the generated e-mail.
- */
-typedef struct {
-	unsigned int version;
-
-	/** see `git_diff_format_email_flags_t` above */
-	uint32_t flags;
-
-	/** This patch number */
-	size_t patch_no;
-
-	/** Total number of patches in this series */
-	size_t total_patches;
-
-	/** id to use for the commit */
-	const git_oid *id;
-
-	/** Summary of the change */
-	const char *summary;
-
-	/** Commit message's body */
-	const char *body;
-
-	/** Author of the change */
-	const git_signature *author;
-} git_diff_format_email_options;
-
-#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION 1
-#define GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT {GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION, 0, 1, 1, NULL, NULL, NULL, NULL}
-
-/**
- * Create an e-mail ready patch from a diff.
- *
- * @param out buffer to store the e-mail patch in
- * @param diff containing the commit
- * @param opts structure with options to influence content and formatting.
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_diff_format_email(
-	git_buf *out,
-	git_diff *diff,
-	const git_diff_format_email_options *opts);
-
-/**
- * Create an e-mail ready patch for a commit.
- *
- * Does not support creating patches for merge commits (yet).
- *
- * @param out buffer to store the e-mail patch in
- * @param repo containing the commit
- * @param commit pointer to up commit
- * @param patch_no patch number of the commit
- * @param total_patches total number of patches in the patch set
- * @param flags determines the formatting of the e-mail
- * @param diff_opts structure with options to influence diff or NULL for defaults.
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_diff_commit_as_email(
-	git_buf *out,
-	git_repository *repo,
-	git_commit *commit,
-	size_t patch_no,
-	size_t total_patches,
-	uint32_t flags,
-	const git_diff_options *diff_opts);
-
-/**
- * Initialize git_diff_format_email_options structure
- *
- * Initializes a `git_diff_format_email_options` with default values. Equivalent
- * to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT.
- *
- * @param opts The `git_blame_options` struct to initialize.
- * @param version The struct version; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION`.
- * @return Zero on success; -1 on failure.
- */
-GIT_EXTERN(int) git_diff_format_email_options_init(
-	git_diff_format_email_options *opts,
-	unsigned int version);
-
-/**
  * Patch ID options structure
  *
  * Initialize with `GIT_PATCHID_OPTIONS_INIT`. Alternatively, you can

src/diff.c

@@ -7,13 +7,15 @@
 
 #include "diff.h"
 
-#include "git2/version.h"
-#include "git2/email.h"
-#include "diff_generate.h"
+#include "common.h"
 #include "patch.h"
 #include "email.h"
 #include "commit.h"
 #include "index.h"
+#include "diff_generate.h"
+
+#include "git2/version.h"
+#include "git2/email.h"
 
 struct patch_id_args {
 	git_hash_ctx ctx;
@@ -152,6 +154,8 @@ int git_diff_foreach(
 	return error;
 }
 
+#ifndef GIT_DEPRECATE_HARD
+
 int git_diff_format_email(
 	git_buf *out,
 	git_diff *diff,
@@ -216,35 +220,16 @@ int git_diff_commit_as_email(
 	return error;
 }
 
-int git_diff_options_init(git_diff_options *opts, unsigned int version)
-{
-	GIT_INIT_STRUCTURE_FROM_TEMPLATE(
-		opts, version, git_diff_options, GIT_DIFF_OPTIONS_INIT);
-	return 0;
-}
-
-#ifndef GIT_DEPRECATE_HARD
 int git_diff_init_options(git_diff_options *opts, unsigned int version)
 {
 	return git_diff_options_init(opts, version);
 }
-#endif
 
-int git_diff_find_options_init(
-	git_diff_find_options *opts, unsigned int version)
-{
-	GIT_INIT_STRUCTURE_FROM_TEMPLATE(
-		opts, version, git_diff_find_options, GIT_DIFF_FIND_OPTIONS_INIT);
-	return 0;
-}
-
-#ifndef GIT_DEPRECATE_HARD
 int git_diff_find_init_options(
 	git_diff_find_options *opts, unsigned int version)
 {
 	return git_diff_find_options_init(opts, version);
 }
-#endif
 
 int git_diff_format_email_options_init(
 	git_diff_format_email_options *opts, unsigned int version)
@@ -255,14 +240,29 @@ int git_diff_format_email_options_init(
 	return 0;
 }
 
-#ifndef GIT_DEPRECATE_HARD
 int git_diff_format_email_init_options(
 	git_diff_format_email_options *opts, unsigned int version)
 {
 	return git_diff_format_email_options_init(opts, version);
 }
+
 #endif
 
+int git_diff_options_init(git_diff_options *opts, unsigned int version)
+{
+	GIT_INIT_STRUCTURE_FROM_TEMPLATE(
+		opts, version, git_diff_options, GIT_DIFF_OPTIONS_INIT);
+	return 0;
+}
+
+int git_diff_find_options_init(
+	git_diff_find_options *opts, unsigned int version)
+{
+	GIT_INIT_STRUCTURE_FROM_TEMPLATE(
+		opts, version, git_diff_find_options, GIT_DIFF_FIND_OPTIONS_INIT);
+	return 0;
+}
+
 static int flush_hunk(git_oid *result, git_hash_ctx *ctx)
 {
 	git_oid hash;

tests/diff/format_email.c

@@ -18,6 +18,7 @@ void test_diff_format_email__cleanup(void)
 	cl_git_sandbox_cleanup();
 }
 
+#ifndef GIT_DEPRECATE_HARD
 static void assert_email_match(
 	const char *expected,
 	const char *oidstr,
@@ -51,9 +52,11 @@ static void assert_email_match(
 	git_commit_free(commit);
 	git_buf_dispose(&buf);
 }
+#endif
 
 void test_diff_format_email__simple(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_diff_format_email_options opts = GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT;
 	const char *email =
 	"From 9264b96c6d104d0e07ae33d3007b6a48246c6f92 Mon Sep 17 00:00:00 2001\n" \
@@ -96,10 +99,12 @@ void test_diff_format_email__simple(void)
 
 	assert_email_match(
 		email, "9264b96c6d104d0e07ae33d3007b6a48246c6f92", &opts);
+#endif
 }
 
 void test_diff_format_email__with_message(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_diff_format_email_options opts = GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT;
 	const char *email = "From 627e7e12d87e07a83fad5b6bfa25e86ead4a5270 Mon Sep 17 00:00:00 2001\n" \
 	"From: Patrick Steinhardt <ps@pks.im>\n" \
@@ -136,11 +141,13 @@ void test_diff_format_email__with_message(void)
 
 	assert_email_match(
 		email, "627e7e12d87e07a83fad5b6bfa25e86ead4a5270", &opts);
+#endif
 }
 
 
 void test_diff_format_email__multiple(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_oid oid;
 	git_commit *commit = NULL;
 	git_diff *diff = NULL;
@@ -256,10 +263,12 @@ void test_diff_format_email__multiple(void)
 	git_diff_free(diff);
 	git_commit_free(commit);
 	git_buf_dispose(&buf);
+#endif
 }
 
 void test_diff_format_email__exclude_marker(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_diff_format_email_options opts = GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT;
 	const char *email =
 	"From 9264b96c6d104d0e07ae33d3007b6a48246c6f92 Mon Sep 17 00:00:00 2001\n" \
@@ -304,10 +313,12 @@ void test_diff_format_email__exclude_marker(void)
 
 	assert_email_match(
 		email, "9264b96c6d104d0e07ae33d3007b6a48246c6f92", &opts);
+#endif
 }
 
 void test_diff_format_email__invalid_no(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_oid oid;
 	git_commit *commit = NULL;
 	git_diff *diff = NULL;
@@ -331,10 +342,12 @@ void test_diff_format_email__invalid_no(void)
 	git_diff_free(diff);
 	git_commit_free(commit);
 	git_buf_dispose(&buf);
+#endif
 }
 
 void test_diff_format_email__mode_change(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_diff_format_email_options opts = GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT;
 	const char *email =
 	"From 7ade76dd34bba4733cf9878079f9fd4a456a9189 Mon Sep 17 00:00:00 2001\n" \
@@ -356,10 +369,12 @@ void test_diff_format_email__mode_change(void)
 
 	assert_email_match(
 		email, "7ade76dd34bba4733cf9878079f9fd4a456a9189", &opts);
+#endif
 }
 
 void test_diff_format_email__rename_add_remove(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_diff_format_email_options opts = GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT;
 	const char *email =
 	"From 6e05acc5a5dab507d91a0a0cc0fb05a3dd98892d Mon Sep 17 00:00:00 2001\n" \
@@ -426,10 +441,12 @@ void test_diff_format_email__rename_add_remove(void)
 
 	assert_email_match(
 		email, "6e05acc5a5dab507d91a0a0cc0fb05a3dd98892d", &opts);
+#endif
 }
 
 void test_diff_format_email__multiline_summary(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_diff_format_email_options opts = GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT;
 	const char *email =
 	"From 9264b96c6d104d0e07ae33d3007b6a48246c6f92 Mon Sep 17 00:00:00 2001\n" \
@@ -474,10 +491,12 @@ void test_diff_format_email__multiline_summary(void)
 
 	assert_email_match(
 		email, "9264b96c6d104d0e07ae33d3007b6a48246c6f92", &opts);
+#endif
 }
 
 void test_diff_format_email__binary(void)
 {
+#ifndef GIT_DEPRECATE_HARD
 	git_diff_format_email_options opts = GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT;
 	const char *email =
 	"From 8d7523f6fcb2404257889abe0d96f093d9f524f9 Mon Sep 17 00:00:00 2001\n" \
@@ -500,5 +519,6 @@ void test_diff_format_email__binary(void)
 
 	assert_email_match(
 		email, "8d7523f6fcb2404257889abe0d96f093d9f524f9", &opts);
+#endif
 }