Documentation/git-format-patch.txt

   1 git-format-patch(1)
   2 ===================
   3
   4 NAME
   5 ----
   6 git-format-patch - Prepare patches for e-mail submission
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
  13                    [--no-thread | --thread[=<style>]]
  14                    [(--attach|--inline)[=<boundary>] | --no-attach]
  15                    [-s | --signoff]
  16                    [-n | --numbered | -N | --no-numbered]
  17                    [--start-number <n>] [--numbered-files]
  18                    [--in-reply-to=Message-Id] [--suffix=.<sfx>]
  19                    [--ignore-if-in-upstream]
  20                    [--subject-prefix=Subject-Prefix]
  21                    [--cc=<email>]
  22                    [--cover-letter]
  23                    [<common diff options>]
  24                    [ <since> | <revision range> ]
  25
  26 DESCRIPTION
  27 -----------
  28
  29 Prepare each commit with its patch in
  30 one file per commit, formatted to resemble UNIX mailbox format.
  31 The output of this command is convenient for e-mail submission or
  32 for use with 'git am'.
  33
  34 There are two ways to specify which commits to operate on.
  35
  36 1. A single commit, <since>, specifies that the commits leading
  37    to the tip of the current branch that are not in the history
  38    that leads to the <since> to be output.
  39
  40 2. Generic <revision range> expression (see "SPECIFYING
  41    REVISIONS" section in linkgit:git-rev-parse[1]) means the
  42    commits in the specified range.
  43
  44 The first rule takes precedence in the case of a single <commit>.  To
  45 apply the second rule, i.e., format everything since the beginning of
  46 history up until <commit>, use the '\--root' option: `git format-patch
  47 \--root <commit>`.  If you want to format only <commit> itself, you
  48 can do this with `git format-patch -1 <commit>`.
  49
  50 By default, each output file is numbered sequentially from 1, and uses the
  51 first line of the commit message (massaged for pathname safety) as
  52 the filename. With the `--numbered-files` option, the output file names
  53 will only be numbers, without the first line of the commit appended.
  54 The names of the output files are printed to standard
  55 output, unless the `--stdout` option is specified.
  56
  57 If `-o` is specified, output files are created in <dir>.  Otherwise
  58 they are created in the current working directory.
  59
  60 By default, the subject of a single patch is "[PATCH] First Line" and
  61 the subject when multiple patches are output is "[PATCH n/m] First
  62 Line". To force 1/1 to be added for a single patch, use `-n`.  To omit
  63 patch numbers from the subject, use `-N`.
  64
  65 If given `--thread`, `git-format-patch` will generate `In-Reply-To` and
  66 `References` headers to make the second and subsequent patch mails appear
  67 as replies to the first mail; this also generates a `Message-Id` header to
  68 reference.
  69
  70 OPTIONS
  71 -------
  72 :git-format-patch: 1
  73 include::diff-options.txt[]
  74
  75 -<n>::
  76         Limits the number of patches to prepare.
  77
  78 -o <dir>::
  79 --output-directory <dir>::
  80         Use <dir> to store the resulting files, instead of the
  81         current working directory.
  82
  83 -n::
  84 --numbered::
  85         Name output in '[PATCH n/m]' format, even with a single patch.
  86
  87 -N::
  88 --no-numbered::
  89         Name output in '[PATCH]' format.
  90
  91 --start-number <n>::
  92         Start numbering the patches at <n> instead of 1.
  93
  94 --numbered-files::
  95         Output file names will be a simple number sequence
  96         without the default first line of the commit appended.
  97
  98 -k::
  99 --keep-subject::
 100         Do not strip/add '[PATCH]' from the first line of the
 101         commit log message.
 102
 103 -s::
 104 --signoff::
 105         Add `Signed-off-by:` line to the commit message, using
 106         the committer identity of yourself.
 107
 108 --stdout::
 109         Print all commits to the standard output in mbox format,
 110         instead of creating a file for each one.
 111
 112 --attach[=<boundary>]::
 113         Create multipart/mixed attachment, the first part of
 114         which is the commit message and the patch itself in the
 115         second part, with `Content-Disposition: attachment`.
 116
 117 --no-attach::
 118         Disable the creation of an attachment, overriding the
 119         configuration setting.
 120
 121 --inline[=<boundary>]::
 122         Create multipart/mixed attachment, the first part of
 123         which is the commit message and the patch itself in the
 124         second part, with `Content-Disposition: inline`.
 125
 126 --thread[=<style>]::
 127 --no-thread::
 128         Controls addition of `In-Reply-To` and `References` headers to
 129         make the second and subsequent mails appear as replies to the
 130         first.  Also controls generation of the `Message-Id` header to
 131         reference.
 132 +
 133 The optional <style> argument can be either `shallow` or `deep`.
 134 'shallow' threading makes every mail a reply to the head of the
 135 series, where the head is chosen from the cover letter, the
 136 `\--in-reply-to`, and the first patch mail, in this order.  'deep'
 137 threading makes every mail a reply to the previous one.
 138 +
 139 The default is `--no-thread`, unless the 'format.thread' configuration
 140 is set.  If `--thread` is specified without a style, it defaults to the
 141 style specified by 'format.thread' if any, or else `shallow`.
 142 +
 143 Beware that the default for 'git send-email' is to thread emails
 144 itself.  If you want `git format-patch` to take care of threading, you
 145 will want to ensure that threading is disabled for `git send-email`.
 146
 147 --in-reply-to=Message-Id::
 148         Make the first mail (or all the mails with `--no-thread`) appear as a
 149         reply to the given Message-Id, which avoids breaking threads to
 150         provide a new patch series.
 151
 152 --ignore-if-in-upstream::
 153         Do not include a patch that matches a commit in
 154         <until>..<since>.  This will examine all patches reachable
 155         from <since> but not from <until> and compare them with the
 156         patches being generated, and any patch that matches is
 157         ignored.
 158
 159 --subject-prefix=<Subject-Prefix>::
 160         Instead of the standard '[PATCH]' prefix in the subject
 161         line, instead use '[<Subject-Prefix>]'. This
 162         allows for useful naming of a patch series, and can be
 163         combined with the `--numbered` option.
 164
 165 --cc=<email>::
 166         Add a `Cc:` header to the email headers. This is in addition
 167         to any configured headers, and may be used multiple times.
 168
 169 --add-header=<header>::
 170         Add an arbitrary header to the email headers.  This is in addition
 171         to any configured headers, and may be used multiple times.
 172         For example, `--add-header="Organization: git-foo"`
 173
 174 --cover-letter::
 175         In addition to the patches, generate a cover letter file
 176         containing the shortlog and the overall diffstat.  You can
 177         fill in a description in the file before sending it out.
 178
 179 --suffix=.<sfx>::
 180         Instead of using `.patch` as the suffix for generated
 181         filenames, use specified suffix.  A common alternative is
 182         `--suffix=.txt`.  Leaving this empty will remove the `.patch`
 183         suffix.
 184 +
 185 Note that the leading character does not have to be a dot; for example,
 186 you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
 187
 188 --no-binary::
 189         Do not output contents of changes in binary files, instead
 190         display a notice that those files changed.  Patches generated
 191         using this option cannot be applied properly, but they are
 192         still useful for code review.
 193
 194 --root::
 195         Treat the revision argument as a <revision range>, even if it
 196         is just a single commit (that would normally be treated as a
 197         <since>).  Note that root commits included in the specified
 198         range are always formatted as creation patches, independently
 199         of this flag.
 200
 201 CONFIGURATION
 202 -------------
 203 You can specify extra mail header lines to be added to each message,
 204 defaults for the subject prefix and file suffix, number patches when
 205 outputting more than one patch, add "Cc:" headers, configure attachments,
 206 and sign off patches with configuration variables.
 207
 208 ------------
 209 [format]
 210         headers = "Organization: git-foo\n"
 211         subjectprefix = CHANGE
 212         suffix = .txt
 213         numbered = auto
 214         cc = <email>
 215         attach [ = mime-boundary-string ]
 216         signoff = true
 217 ------------
 218
 219
 220 EXAMPLES
 221 --------
 222
 223 * Extract commits between revisions R1 and R2, and apply them on top of
 224 the current branch using 'git am' to cherry-pick them:
 225 +
 226 ------------
 227 $ git format-patch -k --stdout R1..R2 | git am -3 -k
 228 ------------
 229
 230 * Extract all commits which are in the current branch but not in the
 231 origin branch:
 232 +
 233 ------------
 234 $ git format-patch origin
 235 ------------
 236 +
 237 For each commit a separate file is created in the current directory.
 238
 239 * Extract all commits that lead to 'origin' since the inception of the
 240 project:
 241 +
 242 ------------
 243 $ git format-patch --root origin
 244 ------------
 245
 246 * The same as the previous one:
 247 +
 248 ------------
 249 $ git format-patch -M -B origin
 250 ------------
 251 +
 252 Additionally, it detects and handles renames and complete rewrites
 253 intelligently to produce a renaming patch.  A renaming patch reduces
 254 the amount of text output, and generally makes it easier to review.
 255 Note that non-git "patch" programs won't understand renaming patches, so
 256 use it only when you know the recipient uses git to apply your patch.
 257
 258 * Extract three topmost commits from the current branch and format them
 259 as e-mailable patches:
 260 +
 261 ------------
 262 $ git format-patch -3
 263 ------------
 264
 265 SEE ALSO
 266 --------
 267 linkgit:git-am[1], linkgit:git-send-email[1]
 268
 269
 270 Author
 271 ------
 272 Written by Junio C Hamano <gitster@pobox.com>
 273
 274 Documentation
 275 --------------
 276 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 277
 278 GIT
 279 ---
 280 Part of the linkgit:git[1] suite