include/git2/email.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_git_email_h__
0008 #define INCLUDE_git_email_h__
0009
0010 #include "common.h"
0011
0012 /**
0013  * @file git2/email.h
0014  * @brief Git email formatting and application routines.
0015  * @ingroup Git
0016  * @{
0017  */
0018 GIT_BEGIN_DECL
0019
0020 /**
0021  * Formatting options for diff e-mail generation
0022  */
0023 typedef enum {
0024     /** Normal patch, the default */
0025     GIT_EMAIL_CREATE_DEFAULT = 0,
0026
0027     /** Do not include patch numbers in the subject prefix. */
0028     GIT_EMAIL_CREATE_OMIT_NUMBERS = (1u << 0),
0029
0030     /**
0031      * Include numbers in the subject prefix even when the
0032      * patch is for a single commit (1/1).
0033      */
0034     GIT_EMAIL_CREATE_ALWAYS_NUMBER = (1u << 1),
0035
0036     /** Do not perform rename or similarity detection. */
0037     GIT_EMAIL_CREATE_NO_RENAMES = (1u << 2)
0038 } git_email_create_flags_t;
0039
0040 /**
0041  * Options for controlling the formatting of the generated e-mail.
0042  */
0043 typedef struct {
0044     unsigned int version;
0045
0046     /** see `git_email_create_flags_t` above */
0047     uint32_t flags;
0048
0049     /** Options to use when creating diffs */
0050     git_diff_options diff_opts;
0051
0052     /** Options for finding similarities within diffs */
0053     git_diff_find_options diff_find_opts;
0054
0055     /**
0056      * The subject prefix, by default "PATCH".  If set to an empty
0057      * string ("") then only the patch numbers will be shown in the
0058      * prefix.  If the subject_prefix is empty and patch numbers
0059      * are not being shown, the prefix will be omitted entirely.
0060      */
0061     const char *subject_prefix;
0062
0063     /**
0064      * The starting patch number; this cannot be 0.  By default,
0065      * this is 1.
0066      */
0067     size_t start_number;
0068
0069     /** The "re-roll" number.  By default, there is no re-roll. */
0070     size_t reroll_number;
0071 } git_email_create_options;
0072
0073 /*
0074  * By default, our options include rename detection and binary
0075  * diffs to match `git format-patch`.
0076  */
0077 #define GIT_EMAIL_CREATE_OPTIONS_VERSION 1
0078 #define GIT_EMAIL_CREATE_OPTIONS_INIT \
0079 { \
0080     GIT_EMAIL_CREATE_OPTIONS_VERSION, \
0081     GIT_EMAIL_CREATE_DEFAULT, \
0082     { GIT_DIFF_OPTIONS_VERSION, GIT_DIFF_SHOW_BINARY, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3 }, \
0083     GIT_DIFF_FIND_OPTIONS_INIT \
0084 }
0085
0086 /**
0087  * Create a diff for a commit in mbox format for sending via email.
0088  *
0089  * @param out buffer to store the e-mail patch in
0090  * @param diff the changes to include in the email
0091  * @param patch_idx the patch index
0092  * @param patch_count the total number of patches that will be included
0093  * @param commit_id the commit id for this change
0094  * @param summary the commit message for this change
0095  * @param body optional text to include above the diffstat
0096  * @param author the person who authored this commit
0097  * @param opts email creation options
0098  */
0099 GIT_EXTERN(int) git_email_create_from_diff(
0100     git_buf *out,
0101     git_diff *diff,
0102     size_t patch_idx,
0103     size_t patch_count,
0104     const git_oid *commit_id,
0105     const char *summary,
0106     const char *body,
0107     const git_signature *author,
0108     const git_email_create_options *opts);
0109
0110 /**
0111  * Create a diff for a commit in mbox format for sending via email.
0112  * The commit must not be a merge commit.
0113  *
0114  * @param out buffer to store the e-mail patch in
0115  * @param commit commit to create a patch for
0116  * @param opts email creation options
0117  */
0118 GIT_EXTERN(int) git_email_create_from_commit(
0119     git_buf *out,
0120     git_commit *commit,
0121     const git_email_create_options *opts);
0122
0123 GIT_END_DECL
0124
0125 /** @} */
0126
0127 #endif