1 /* 2 * Copyright (C) the libgit2 contributors. All rights reserved. 3 * 4 * This file is part of libgit2, distributed under the GNU GPL v2 with 5 * a Linking Exception. For full terms see the included COPYING file. 6 */ 7 #ifndef INCLUDE_git_email_h__ 8 #define INCLUDE_git_email_h__ 9 10 #include "common.h" 11 12 /** 13 * @file git2/email.h 14 * @brief Git email formatting and application routines. 15 * @ingroup Git 16 * @{ 17 */ 18 GIT_BEGIN_DECL 19 20 /** 21 * Formatting options for diff e-mail generation 22 */ 23 typedef enum { 24 /** Normal patch, the default */ 25 GIT_EMAIL_CREATE_DEFAULT = 0, 26 27 /** Do not include patch numbers in the subject prefix. */ 28 GIT_EMAIL_CREATE_OMIT_NUMBERS = (1u << 0), 29 30 /** 31 * Include numbers in the subject prefix even when the 32 * patch is for a single commit (1/1). 33 */ 34 GIT_EMAIL_CREATE_ALWAYS_NUMBER = (1u << 1), 35 36 /** Do not perform rename or similarity detection. */ 37 GIT_EMAIL_CREATE_NO_RENAMES = (1u << 2), 38 } git_email_create_flags_t; 39 40 /** 41 * Options for controlling the formatting of the generated e-mail. 42 */ 43 typedef struct { 44 unsigned int version; 45 46 /** see `git_email_create_flags_t` above */ 47 uint32_t flags; 48 49 /** Options to use when creating diffs */ 50 git_diff_options diff_opts; 51 52 /** Options for finding similarities within diffs */ 53 git_diff_find_options diff_find_opts; 54 55 /** 56 * The subject prefix, by default "PATCH". If set to an empty 57 * string ("") then only the patch numbers will be shown in the 58 * prefix. If the subject_prefix is empty and patch numbers 59 * are not being shown, the prefix will be omitted entirely. 60 */ 61 const char *subject_prefix; 62 63 /** 64 * The starting patch number; this cannot be 0. By default, 65 * this is 1. 66 */ 67 size_t start_number; 68 69 /** The "re-roll" number. By default, there is no re-roll. */ 70 size_t reroll_number; 71 } git_email_create_options; 72 73 /* 74 * By default, our options include rename detection and binary 75 * diffs to match `git format-patch`. 76 */ 77 #define GIT_EMAIL_CREATE_OPTIONS_VERSION 1 78 #define GIT_EMAIL_CREATE_OPTIONS_INIT \ 79 { \ 80 GIT_EMAIL_CREATE_OPTIONS_VERSION, \ 81 GIT_EMAIL_CREATE_DEFAULT, \ 82 { GIT_DIFF_OPTIONS_VERSION, GIT_DIFF_SHOW_BINARY, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3 }, \ 83 GIT_DIFF_FIND_OPTIONS_INIT \ 84 } 85 86 /** 87 * Create a diff for a commit in mbox format for sending via email. 88 * 89 * @param out buffer to store the e-mail patch in 90 * @param diff the changes to include in the email 91 * @param patch_idx the patch index 92 * @param patch_count the total number of patches that will be included 93 * @param commit_id the commit id for this change 94 * @param summary the commit message for this change 95 * @param body optional text to include above the diffstat 96 * @param author the person who authored this commit 97 * @param opts email creation options 98 */ 99 GIT_EXTERN(int) git_email_create_from_diff( 100 git_buf *out, 101 git_diff *diff, 102 size_t patch_idx, 103 size_t patch_count, 104 const git_oid *commit_id, 105 const char *summary, 106 const char *body, 107 const git_signature *author, 108 const git_email_create_options *opts); 109 110 /** 111 * Create a diff for a commit in mbox format for sending via email. 112 * The commit must not be a merge commit. 113 * 114 * @param out buffer to store the e-mail patch in 115 * @param commit commit to create a patch for 116 * @param opts email creation options 117 */ 118 GIT_EXTERN(int) git_email_create_from_commit( 119 git_buf *out, 120 git_commit *commit, 121 const git_email_create_options *opts); 122 123 GIT_END_DECL 124 125 /** @} */ 126 127 #endif 128