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.  You can also specify
 130 new defaults for the subject prefix and file suffix.
 131
 132 ------------
 133 [format]
 134         headers = "Organization: git-foo\n"
 135         subjectprefix = CHANGE
 136         suffix = .txt
 137 ------------
 138
 139
 140 EXAMPLES
 141 --------
 142
 143 git-format-patch -k --stdout R1..R2 | git-am -3 -k::
 144         Extract commits between revisions R1 and R2, and apply
 145         them on top of the current branch using `git-am` to
 146         cherry-pick them.
 147
 148 git-format-patch origin::
 149         Extract all commits which are in the current branch but
 150         not in the origin branch.  For each commit a separate file
 151         is created in the current directory.
 152
 153 git-format-patch -M -B origin::
 154         The same as the previous one.  Additionally, it detects
 155         and handles renames and complete rewrites intelligently to
 156         produce a renaming patch.  A renaming patch reduces the
 157         amount of text output, and generally makes it easier to
 158         review it.  Note that the "patch" program does not
 159         understand renaming patches, so use it only when you know
 160         the recipient uses git to apply your patch.
 161
 162 git-format-patch -3::
 163         Extract three topmost commits from the current branch
 164         and format them as e-mailable patches.
 165
 166 See Also
 167 --------
 168 gitlink:git-am[1], gitlink:git-send-email[1]
 169
 170
 171 Author
 172 ------
 173 Written by Junio C Hamano <junkio@cox.net>
 174
 175 Documentation
 176 --------------
 177 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 178
 179 GIT
 180 ---
 181 Part of the gitlink:git[7] suite