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