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                    [--to=<email>] [--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 --to=<email>::
 166         Add a `To:` header to the email headers. This is in addition
 167         to any configured headers, and may be used multiple times.
 168
 169 --cc=<email>::
 170         Add a `Cc:` header to the email headers. This is in addition
 171         to any configured headers, and may be used multiple times.
 172
 173 --add-header=<header>::
 174         Add an arbitrary header to the email headers.  This is in addition
 175         to any configured headers, and may be used multiple times.
 176         For example, `--add-header="Organization: git-foo"`
 177
 178 --cover-letter::
 179         In addition to the patches, generate a cover letter file
 180         containing the shortlog and the overall diffstat.  You can
 181         fill in a description in the file before sending it out.
 182
 183 --suffix=.<sfx>::
 184         Instead of using `.patch` as the suffix for generated
 185         filenames, use specified suffix.  A common alternative is
 186         `--suffix=.txt`.  Leaving this empty will remove the `.patch`
 187         suffix.
 188 +
 189 Note that the leading character does not have to be a dot; for example,
 190 you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
 191
 192 --no-binary::
 193         Do not output contents of changes in binary files, instead
 194         display a notice that those files changed.  Patches generated
 195         using this option cannot be applied properly, but they are
 196         still useful for code review.
 197
 198 --root::
 199         Treat the revision argument as a <revision range>, even if it
 200         is just a single commit (that would normally be treated as a
 201         <since>).  Note that root commits included in the specified
 202         range are always formatted as creation patches, independently
 203         of this flag.
 204
 205 CONFIGURATION
 206 -------------
 207 You can specify extra mail header lines to be added to each message,
 208 defaults for the subject prefix and file suffix, number patches when
 209 outputting more than one patch, add "To" or "Cc:" headers, configure
 210 attachments, and sign off patches with configuration variables.
 211
 212 ------------
 213 [format]
 214         headers = "Organization: git-foo\n"
 215         subjectprefix = CHANGE
 216         suffix = .txt
 217         numbered = auto
 218         to = <email>
 219         cc = <email>
 220         attach [ = mime-boundary-string ]
 221         signoff = true
 222 ------------
 223
 224
 225 EXAMPLES
 226 --------
 227
 228 * Extract commits between revisions R1 and R2, and apply them on top of
 229 the current branch using 'git am' to cherry-pick them:
 230 +
 231 ------------
 232 $ git format-patch -k --stdout R1..R2 | git am -3 -k
 233 ------------
 234
 235 * Extract all commits which are in the current branch but not in the
 236 origin branch:
 237 +
 238 ------------
 239 $ git format-patch origin
 240 ------------
 241 +
 242 For each commit a separate file is created in the current directory.
 243
 244 * Extract all commits that lead to 'origin' since the inception of the
 245 project:
 246 +
 247 ------------
 248 $ git format-patch --root origin
 249 ------------
 250
 251 * The same as the previous one:
 252 +
 253 ------------
 254 $ git format-patch -M -B origin
 255 ------------
 256 +
 257 Additionally, it detects and handles renames and complete rewrites
 258 intelligently to produce a renaming patch.  A renaming patch reduces
 259 the amount of text output, and generally makes it easier to review.
 260 Note that non-git "patch" programs won't understand renaming patches, so
 261 use it only when you know the recipient uses git to apply your patch.
 262
 263 * Extract three topmost commits from the current branch and format them
 264 as e-mailable patches:
 265 +
 266 ------------
 267 $ git format-patch -3
 268 ------------
 269
 270 SEE ALSO
 271 --------
 272 linkgit:git-am[1], linkgit:git-send-email[1]
 273
 274
 275 Author
 276 ------
 277 Written by Junio C Hamano <gitster@pobox.com>
 278
 279 Documentation
 280 --------------
 281 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 282
 283 GIT
 284 ---
 285 Part of the linkgit:git[1] suite