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] [--quiet]
  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[7]) 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 --quiet::
 200         Do not print the names of the generated files to standard output.
 201
 202 --no-binary::
 203         Do not output contents of changes in binary files, instead
 204         display a notice that those files changed.  Patches generated
 205         using this option cannot be applied properly, but they are
 206         still useful for code review.
 207
 208 --root::
 209         Treat the revision argument as a <revision range>, even if it
 210         is just a single commit (that would normally be treated as a
 211         <since>).  Note that root commits included in the specified
 212         range are always formatted as creation patches, independently
 213         of this flag.
 214
 215 CONFIGURATION
 216 -------------
 217 You can specify extra mail header lines to be added to each message,
 218 defaults for the subject prefix and file suffix, number patches when
 219 outputting more than one patch, add "To" or "Cc:" headers, configure
 220 attachments, and sign off patches with configuration variables.
 221
 222 ------------
 223 [format]
 224         headers = "Organization: git-foo\n"
 225         subjectprefix = CHANGE
 226         suffix = .txt
 227         numbered = auto
 228         to = <email>
 229         cc = <email>
 230         attach [ = mime-boundary-string ]
 231         signoff = true
 232 ------------
 233
 234
 235 EXAMPLES
 236 --------
 237
 238 * Extract commits between revisions R1 and R2, and apply them on top of
 239 the current branch using 'git am' to cherry-pick them:
 240 +
 241 ------------
 242 $ git format-patch -k --stdout R1..R2 | git am -3 -k
 243 ------------
 244
 245 * Extract all commits which are in the current branch but not in the
 246 origin branch:
 247 +
 248 ------------
 249 $ git format-patch origin
 250 ------------
 251 +
 252 For each commit a separate file is created in the current directory.
 253
 254 * Extract all commits that lead to 'origin' since the inception of the
 255 project:
 256 +
 257 ------------
 258 $ git format-patch --root origin
 259 ------------
 260
 261 * The same as the previous one:
 262 +
 263 ------------
 264 $ git format-patch -M -B origin
 265 ------------
 266 +
 267 Additionally, it detects and handles renames and complete rewrites
 268 intelligently to produce a renaming patch.  A renaming patch reduces
 269 the amount of text output, and generally makes it easier to review.
 270 Note that non-git "patch" programs won't understand renaming patches, so
 271 use it only when you know the recipient uses git to apply your patch.
 272
 273 * Extract three topmost commits from the current branch and format them
 274 as e-mailable patches:
 275 +
 276 ------------
 277 $ git format-patch -3
 278 ------------
 279
 280 SEE ALSO
 281 --------
 282 linkgit:git-am[1], linkgit:git-send-email[1]
 283
 284 GIT
 285 ---
 286 Part of the linkgit:git[1] suite