include/git2/email.h

   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