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' [-n | -k] [-o <dir> | --stdout] [--thread]
  13                    [--attach[=<boundary>] | --inline[=<boundary>]]
  14                    [-s | --signoff] [<common diff options>]
  15                    [--start-number <n>] [--numbered-files]
  16                    [--in-reply-to=Message-Id] [--suffix=.<sfx>]
  17                    [--ignore-if-in-upstream]
  18                    [--subject-prefix=Subject-Prefix]
  19                    <since>[..<until>]
  20
  21 DESCRIPTION
  22 -----------
  23
  24 Prepare each commit between <since> and <until> with its patch in
  25 one file per commit, formatted to resemble UNIX mailbox format.
  26 If ..<until> is not specified, the head of the current working
  27 tree is implied.  For a more complete list of ways to spell
  28 <since> and <until>, see "SPECIFYING REVISIONS" section in
  29 gitlink:git-rev-parse[1].
  30
  31 The output of this command is convenient for e-mail submission or
  32 for use with gitlink:git-am[1].
  33
  34 By default, each output file is numbered sequentially from 1, and uses the
  35 first line of the commit message (massaged for pathname safety) as
  36 the filename. With the --numbered-files option, the output file names
  37 will only be numbers, without the first line of the commit appended.
  38 The names of the output files are printed to standard
  39 output, unless the --stdout option is specified.
  40
  41 If -o is specified, output files are created in <dir>.  Otherwise
  42 they are created in the current working directory.
  43
  44 If -n is specified, instead of "[PATCH] Subject", the first line
  45 is formatted as "[PATCH n/m] Subject".
  46
  47 If given --thread, git-format-patch will generate In-Reply-To and
  48 References headers to make the second and subsequent patch mails appear
  49 as replies to the first mail; this also generates a Message-Id header to
  50 reference.
  51
  52 OPTIONS
  53 -------
  54 include::diff-options.txt[]
  55
  56 -<n>::
  57         Limits the number of patches to prepare.
  58
  59 -o|--output-directory <dir>::
  60         Use <dir> to store the resulting files, instead of the
  61         current working directory.
  62
  63 -n|--numbered::
  64         Name output in '[PATCH n/m]' format.
  65
  66 --start-number <n>::
  67         Start numbering the patches at <n> instead of 1.
  68
  69 --numbered-files::
  70         Output file names will be a simple number sequence
  71         without the default first line of the commit appended.
  72         Mutually exclusive with the --stdout option.
  73
  74 -k|--keep-subject::
  75         Do not strip/add '[PATCH]' from the first line of the
  76         commit log message.
  77
  78 -s|--signoff::
  79         Add `Signed-off-by:` line to the commit message, using
  80         the committer identity of yourself.
  81
  82 --stdout::
  83         Print all commits to the standard output in mbox format,
  84         instead of creating a file for each one.
  85
  86 --attach[=<boundary>]::
  87         Create multipart/mixed attachment, the first part of
  88         which is the commit message and the patch itself in the
  89         second part, with "Content-Disposition: attachment".
  90
  91 --inline[=<boundary>]::
  92         Create multipart/mixed attachment, the first part of
  93         which is the commit message and the patch itself in the
  94         second part, with "Content-Disposition: inline".
  95
  96 --thread::
  97         Add In-Reply-To and References headers to make the second and
  98         subsequent mails appear as replies to the first.  Also generates
  99         the Message-Id header to reference.
 100
 101 --in-reply-to=Message-Id::
 102         Make the first mail (or all the mails with --no-thread) appear as a
 103         reply to the given Message-Id, which avoids breaking threads to
 104         provide a new patch series.
 105
 106 --ignore-if-in-upstream::
 107         Do not include a patch that matches a commit in
 108         <until>..<since>.  This will examine all patches reachable
 109         from <since> but not from <until> and compare them with the
 110         patches being generated, and any patch that matches is
 111         ignored.
 112
 113 --subject-prefix=<Subject-Prefix>::
 114         Instead of the standard '[PATCH]' prefix in the subject
 115         line, instead use '[<Subject-Prefix>]'. This
 116         allows for useful naming of a patch series, and can be
 117         combined with the --numbered option.
 118
 119 --suffix=.<sfx>::
 120         Instead of using `.patch` as the suffix for generated
 121         filenames, use specified suffix.  A common alternative is
 122         `--suffix=.txt`.
 123 +
 124 Note that you would need to include the leading dot `.` if you
 125 want a filename like `0001-description-of-my-change.patch`, and
 126 the first letter does not have to be a dot.  Leaving it empty would
 127 not add any suffix.
 128
 129 CONFIGURATION
 130 -------------
 131 You can specify extra mail header lines to be added to each
 132 message in the repository configuration.  You can also specify
 133 new defaults for the subject prefix and file suffix.
 134
 135 ------------
 136 [format]
 137         headers = "Organization: git-foo\n"
 138         subjectprefix = CHANGE
 139         suffix = .txt
 140 ------------
 141
 142
 143 EXAMPLES
 144 --------
 145
 146 git-format-patch -k --stdout R1..R2 | git-am -3 -k::
 147         Extract commits between revisions R1 and R2, and apply
 148         them on top of the current branch using `git-am` to
 149         cherry-pick them.
 150
 151 git-format-patch origin::
 152         Extract all commits which are in the current branch but
 153         not in the origin branch.  For each commit a separate file
 154         is created in the current directory.
 155
 156 git-format-patch -M -B origin::
 157         The same as the previous one.  Additionally, it detects
 158         and handles renames and complete rewrites intelligently to
 159         produce a renaming patch.  A renaming patch reduces the
 160         amount of text output, and generally makes it easier to
 161         review it.  Note that the "patch" program does not
 162         understand renaming patches, so use it only when you know
 163         the recipient uses git to apply your patch.
 164
 165 git-format-patch -3::
 166         Extract three topmost commits from the current branch
 167         and format them as e-mailable patches.
 168
 169 See Also
 170 --------
 171 gitlink:git-am[1], gitlink:git-send-email[1]
 172
 173
 174 Author
 175 ------
 176 Written by Junio C Hamano <junkio@cox.net>
 177
 178 Documentation
 179 --------------
 180 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 181
 182 GIT
 183 ---
 184 Part of the gitlink:git[7] suite