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