Say when --track is useful in the git-checkout docs.
[gitweb.git] / Documentation / git-format-patch.txt
index 7cc7fafc1d7fbe380ffa53e0d028886e15d0010e..c9857a2d62e55edaf7e71c1a89ae09c8ae2423d2 100644 (file)
@@ -9,30 +9,67 @@ git-format-patch - Prepare patches for e-mail submission
 SYNOPSIS
 --------
 [verse]
-'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--attach] [-s] [-c]
-                [--diff-options] <his> [<mine>]
+'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--thread]
+                   [--attach[=<boundary>] | --inline[=<boundary>]]
+                   [-s | --signoff] [<common diff options>]
+                   [--start-number <n>] [--numbered-files]
+                   [--in-reply-to=Message-Id] [--suffix=.<sfx>]
+                   [--ignore-if-in-upstream]
+                   [--subject-prefix=Subject-Prefix]
+                  [ <since> | <revision range> ]
 
 DESCRIPTION
 -----------
-Prepare each commit with its patch since <mine> head forked from
-<his> head, one file per patch formatted to resemble UNIX mailbox
-format, for e-mail submission or use with gitlink:git-am[1].
 
-Each output file is numbered sequentially from 1, and uses the
-first line of the commit message (massaged for pathname safety)
-as the filename.
+Prepare each commit with its patch in
+one file per commit, formatted to resemble UNIX mailbox format.
+The output of this command is convenient for e-mail submission or
+for use with gitlink:git-am[1].
 
-When -o is specified, output files are created in <dir>; otherwise
-they are created in the current working directory.  This option
-is ignored if --stdout is specified.
+There are two ways to specify which commits to operate on.
 
-When -n is specified, instead of "[PATCH] Subject", the first
-line is formatted as "[PATCH N/M] Subject", unless you have only
-one patch.
+1. A single commit, <since>, specifies that the commits leading
+   to the tip of the current branch that are not in the history
+   that leads to the <since> to be output.
 
+2. Generic <revision range> expression (see "SPECIFYING
+   REVISIONS" section in gitlink:git-rev-parse[1]) means the
+   commits in the specified range.
+
+A single commit, when interpreted as a <revision range>
+expression, means "everything that leads to that commit", but
+if you write 'git format-patch <commit>', the previous rule
+applies to that command line and you do not get "everything
+since the beginning of the time".  If you want to format
+everything since project inception to one commit, say "git
+format-patch \--root <commit>" to make it clear that it is the
+latter case.
+
+By default, each output file is numbered sequentially from 1, and uses the
+first line of the commit message (massaged for pathname safety) as
+the filename. With the --numbered-files option, the output file names
+will only be numbers, without the first line of the commit appended.
+The names of the output files are printed to standard
+output, unless the --stdout option is specified.
+
+If -o is specified, output files are created in <dir>.  Otherwise
+they are created in the current working directory.
+
+If -n is specified, instead of "[PATCH] Subject", the first line
+is formatted as "[PATCH n/m] Subject".
+
+If given --thread, git-format-patch will generate In-Reply-To and
+References headers to make the second and subsequent patch mails appear
+as replies to the first mail; this also generates a Message-Id header to
+reference.
 
 OPTIONS
 -------
+include::diff-options.txt[]
+
+-<n>::
+       Limits the number of patches to prepare.
+
 -o|--output-directory <dir>::
        Use <dir> to store the resulting files, instead of the
        current working directory.
@@ -40,6 +77,14 @@ OPTIONS
 -n|--numbered::
        Name output in '[PATCH n/m]' format.
 
+--start-number <n>::
+       Start numbering the patches at <n> instead of 1.
+
+--numbered-files::
+       Output file names will be a simple number sequence
+       without the default first line of the commit appended.
+       Mutually exclusive with the --stdout option.
+
 -k|--keep-subject::
        Do not strip/add '[PATCH]' from the first line of the
        commit log message.
@@ -48,29 +93,65 @@ OPTIONS
        Add `Signed-off-by:` line to the commit message, using
        the committer identity of yourself.
 
--c|--check::
-        Display suspicious lines in the patch.  The definition
-        of 'suspicious lines' is currently the lines that has
-        trailing whitespaces, and the lines whose indentation
-        has a SP character immediately followed by a TAB
-        character.
-
 --stdout::
-       This flag generates the mbox formatted output to the
-       standard output, instead of saving them into a file per
-       patch and implies --mbox.
-
---attach::
-       Create attachments instead of inlining patches.
-
+       Print all commits to the standard output in mbox format,
+       instead of creating a file for each one.
+
+--attach[=<boundary>]::
+       Create multipart/mixed attachment, the first part of
+       which is the commit message and the patch itself in the
+       second part, with "Content-Disposition: attachment".
+
+--inline[=<boundary>]::
+       Create multipart/mixed attachment, the first part of
+       which is the commit message and the patch itself in the
+       second part, with "Content-Disposition: inline".
+
+--thread::
+       Add In-Reply-To and References headers to make the second and
+       subsequent mails appear as replies to the first.  Also generates
+       the Message-Id header to reference.
+
+--in-reply-to=Message-Id::
+       Make the first mail (or all the mails with --no-thread) appear as a
+       reply to the given Message-Id, which avoids breaking threads to
+       provide a new patch series.
+
+--ignore-if-in-upstream::
+       Do not include a patch that matches a commit in
+       <until>..<since>.  This will examine all patches reachable
+       from <since> but not from <until> and compare them with the
+       patches being generated, and any patch that matches is
+       ignored.
+
+--subject-prefix=<Subject-Prefix>::
+       Instead of the standard '[PATCH]' prefix in the subject
+       line, instead use '[<Subject-Prefix>]'. This
+       allows for useful naming of a patch series, and can be
+       combined with the --numbered option.
+
+--suffix=.<sfx>::
+       Instead of using `.patch` as the suffix for generated
+       filenames, use specified suffix.  A common alternative is
+       `--suffix=.txt`.
++
+Note that you would need to include the leading dot `.` if you
+want a filename like `0001-description-of-my-change.patch`, and
+the first letter does not have to be a dot.  Leaving it empty would
+not add any suffix.
 
 CONFIGURATION
 -------------
 You can specify extra mail header lines to be added to each
-message in the repository configuration as follows:
+message in the repository configuration.  You can also specify
+new defaults for the subject prefix and file suffix.
 
+------------
 [format]
         headers = "Organization: git-foo\n"
+        subjectprefix = CHANGE
+        suffix = .txt
+------------
 
 
 EXAMPLES
@@ -82,19 +163,26 @@ git-format-patch -k --stdout R1..R2 | git-am -3 -k::
        cherry-pick them.
 
 git-format-patch origin::
-       Extract commits the current branch accumulated since it
-       pulled from origin the last time in a patch form for
-       e-mail submission.
+       Extract all commits which are in the current branch but
+       not in the origin branch.  For each commit a separate file
+       is created in the current directory.
 
-git-format-patch -M -B origin::
-       The same as the previous one, except detect and handle
-       renames and complete rewrites intelligently to produce
-       renaming patch.  A renaming patch reduces the amount of
-       text output, and generally makes it easier to review
-       it.  Note that the "patch" program does not understand
-       renaming patch well, so use it only when you know the
-       recipient uses git to apply your patch.
+git-format-patch \--root origin::
+       Extract all commits which that leads to 'origin' since the
+       inception of the project.
 
+git-format-patch -M -B origin::
+       The same as the previous one.  Additionally, it detects
+       and handles renames and complete rewrites intelligently to
+       produce a renaming patch.  A renaming patch reduces the
+       amount of text output, and generally makes it easier to
+       review it.  Note that the "patch" program does not
+       understand renaming patches, so use it only when you know
+       the recipient uses git to apply your patch.
+
+git-format-patch -3::
+       Extract three topmost commits from the current branch
+       and format them as e-mailable patches.
 
 See Also
 --------
@@ -112,4 +200,3 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 GIT
 ---
 Part of the gitlink:git[7] suite
-