diff options
author | Edward Thomson <ethomson@edwardthomson.com> | 2021-09-20 21:45:10 -0400 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-09-20 21:45:10 -0400 |
commit | ba01547d4a8190d5e4df317d4b0d0767e160bc57 (patch) | |
tree | e2d4d5b54a684f0f5e3b3ae33cdcb3b5e0089cd1 /include | |
parent | 0a8728622ecf77ce4185139761b31f0c6f77f04e (diff) | |
parent | ba3595af0f3f788427868abb0b499da9f82dc9d1 (diff) | |
download | libgit2-ba01547d4a8190d5e4df317d4b0d0767e160bc57.tar.gz |
Merge pull request #6061 from libgit2/ethomson/email
Introduce `git_email_create`; deprecate `git_diff_format_email`
Diffstat (limited to 'include')
-rw-r--r-- | include/git2.h | 1 | ||||
-rw-r--r-- | include/git2/deprecated.h | 96 | ||||
-rw-r--r-- | include/git2/diff.h | 93 | ||||
-rw-r--r-- | include/git2/email.h | 127 | ||||
-rw-r--r-- | include/git2/sys/email.h | 45 |
5 files changed, 269 insertions, 93 deletions
diff --git a/include/git2.h b/include/git2.h index f39d7fbe2..2961cc3e5 100644 --- a/include/git2.h +++ b/include/git2.h @@ -26,6 +26,7 @@ #include "git2/deprecated.h" #include "git2/describe.h" #include "git2/diff.h" +#include "git2/email.h" #include "git2/errors.h" #include "git2/filter.h" #include "git2/global.h" diff --git a/include/git2/deprecated.h b/include/git2/deprecated.h index a2b117f53..6b268eb79 100644 --- a/include/git2/deprecated.h +++ b/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 diff --git a/include/git2/diff.h b/include/git2/diff.h index 9497793c3..a0a15e76f 100644 --- a/include/git2/diff.h +++ b/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 diff --git a/include/git2/email.h b/include/git2/email.h new file mode 100644 index 000000000..b56be5d0e --- /dev/null +++ b/include/git2/email.h @@ -0,0 +1,127 @@ +/* + * 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_git_email_h__ +#define INCLUDE_git_email_h__ + +#include "common.h" + +/** + * @file git2/email.h + * @brief Git email formatting and application routines. + * @ingroup Git + * @{ + */ +GIT_BEGIN_DECL + +/** + * Formatting options for diff e-mail generation + */ +typedef enum { + /** Normal patch, the default */ + GIT_EMAIL_CREATE_DEFAULT = 0, + + /** Do not include patch numbers in the subject prefix. */ + GIT_EMAIL_CREATE_OMIT_NUMBERS = (1u << 0), + + /** + * Include numbers in the subject prefix even when the + * patch is for a single commit (1/1). + */ + GIT_EMAIL_CREATE_ALWAYS_NUMBER = (1u << 1), + + /** Do not perform rename or similarity detection. */ + GIT_EMAIL_CREATE_NO_RENAMES = (1u << 2), +} git_email_create_flags_t; + +/** + * Options for controlling the formatting of the generated e-mail. + */ +typedef struct { + unsigned int version; + + /** see `git_email_create_flags_t` above */ + uint32_t flags; + + /** Options to use when creating diffs */ + git_diff_options diff_opts; + + /** Options for finding similarities within diffs */ + git_diff_find_options diff_find_opts; + + /** + * The subject prefix, by default "PATCH". If set to an empty + * string ("") then only the patch numbers will be shown in the + * prefix. If the subject_prefix is empty and patch numbers + * are not being shown, the prefix will be omitted entirely. + */ + const char *subject_prefix; + + /** + * The starting patch number; this cannot be 0. By default, + * this is 1. + */ + size_t start_number; + + /** The "re-roll" number. By default, there is no re-roll. */ + size_t reroll_number; +} git_email_create_options; + +/* + * By default, our options include rename detection and binary + * diffs to match `git format-patch`. + */ +#define GIT_EMAIL_CREATE_OPTIONS_VERSION 1 +#define GIT_EMAIL_CREATE_OPTIONS_INIT \ +{ \ + GIT_EMAIL_CREATE_OPTIONS_VERSION, \ + GIT_EMAIL_CREATE_DEFAULT, \ + { GIT_DIFF_OPTIONS_VERSION, GIT_DIFF_SHOW_BINARY, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3 }, \ + GIT_DIFF_FIND_OPTIONS_INIT \ +} + +/** + * 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); + +/** + * 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 opts email creation options + */ +GIT_EXTERN(int) git_email_create_from_commit( + git_buf *out, + git_commit *commit, + const git_email_create_options *opts); + +GIT_END_DECL + +/** @} */ + +#endif 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 |