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