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