Provided by:
git-core_1.5.6.3-1.1ubuntu2_i386 
NAME
git-format-patch - Prepare patches for e-mail submission
SYNOPSIS
git-format-patch [-k] [-o <dir> | --stdout] [--thread]
[--attach[=<boundary>] | --inline[=<boundary>]]
[-s | --signoff] [<common diff options>]
[-n | --numbered | -N | --no-numbered]
[--start-number <n>] [--numbered-files]
[--in-reply-to=Message-Id] [--suffix=.<sfx>]
[--ignore-if-in-upstream]
[--subject-prefix=Subject-Prefix]
[--cc=<email>]
[--cover-letter]
[ <since> | <revision range> ]
DESCRIPTION
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 git-am(1).
There are two ways to specify which commits to operate on.
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 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
-p
Generate patches without diffstat.
-u
Synonym for "-p".
-U<n>
Shorthand for "--unified=<n>".
--unified=<n>
Generate diffs with <n> lines of context instead of the usual
three. Implies "-p".
--raw
Generate the raw format.
--patch-with-raw
Synonym for "-p --raw".
--stat[=width[,name-width]]
Generate a diffstat. You can override the default output width for
80-column terminal by "--stat=width". The width of the filename
part can be controlled by giving another width to it separated by a
comma.
--numstat
Similar to --stat, but shows number of added and deleted lines in
decimal notation and pathname without abbreviation, to make it more
machine friendly. For binary files, outputs two - instead of saying
0 0.
--shortstat
Output only the last line of the --stat format containing total
number of modified files, as well as number of added and deleted
lines.
--dirstat[=limit]
Output only the sub-directories that are impacted by a diff, and to
what degree they are impacted. You can override the default cut-off
in percent (3) by "--dirstat=limit". If you want to enable
"cumulative" directory statistics, you can use the "--cumulative"
flag, which adds up percentages recursively even when they have
been already reported for a sub-directory.
--summary
Output a condensed summary of extended header information such as
creations, renames and mode changes.
--patch-with-stat
Synonym for "-p --stat". This is the default.
-z
NUL-line termination on output. This affects the --raw output field
terminator. Also output from commands such as "git-log" will be
delimited with NUL between commits.
--name-only
Show only names of changed files.
--name-status
Show only names and status of changed files. See the description of
the --diff-filter option on what the status letters mean.
--color
Show colored diff.
--no-color
Turn off colored diff, even when the configuration file gives the
default to color output.
--color-words
Show colored word diff, i.e. color words which have changed.
--no-renames
Turn off rename detection, even when the configuration file gives
the default to do so.
--check
Warn if changes introduce trailing whitespace or an indent that
uses a space before a tab. Exits with non-zero status if problems
are found. Not compatible with --exit-code.
--full-index
Instead of the first handful characters, show full object name of
pre- and post-image blob on the "index" line when generating a
patch format output.
--binary
In addition to --full-index, output "binary diff" that can be
applied with "git apply".
--abbrev[=<n>]
Instead of showing the full 40-byte hexadecimal object name in
diff-raw format output and diff-tree header lines, show only
handful hexdigits prefix. This is independent of --full-index
option above, which controls the diff-patch output format. Non
default number of digits can be specified with --abbrev=<n>.
-B
Break complete rewrite changes into pairs of delete and create.
-M
Detect renames.
-C
Detect copies as well as renames. See also --find-copies-harder.
--diff-filter=[ACDMRTUXB*]
Select only files that are Added (A), Copied (C), Deleted (D),
Modified (M), Renamed (R), have their type (mode) changed (T), are
Unmerged (U), are Unknown (X), or have had their pairing Broken
(B). Any combination of the filter characters may be used. When *
(All-or-none) is added to the combination, all paths are selected
if there is any file that matches other criteria in the comparison;
if there is no file that matches other criteria, nothing is
selected.
--find-copies-harder
For performance reasons, by default, -C option finds copies only if
the original file of the copy was modified in the same changeset.
This flag makes the command inspect unmodified files as candidates
for the source of copy. This is a very expensive operation for
large projects, so use it with caution. Giving more than one -C
option has the same effect.
-l<num>
-M and -C options require O(n^2) processing time where n is the
number of potential rename/copy targets. This option prevents
rename/copy detection from running if the number of rename/copy
targets exceeds the specified number.
-S<string>
Look for differences that contain the change in <string>.
--pickaxe-all
When -S finds a change, show all the changes in that changeset, not
just the files that contain the change in <string>.
--pickaxe-regex
Make the <string> not a plain string but an extended POSIX regex to
match.
-O<orderfile>
Output the patch in the order specified in the <orderfile>, which
has one shell glob pattern per line.
-R
Swap two inputs; that is, show differences from index or on-disk
file to tree contents.
--relative[=<path>]
When run from a subdirectory of the project, it can be told to
exclude changes outside the directory and show pathnames relative
to it with this option. When you are not in a subdirectory (e.g. in
a bare repository), you can name which subdirectory to make the
output relative to by giving a <path> as an argument.
--text
Treat all files as text.
-a
Shorthand for "--text".
--ignore-space-at-eol
Ignore changes in whitespace at EOL.
--ignore-space-change
Ignore changes in amount of whitespace. This ignores whitespace at
line end, and considers all other sequences of one or more
whitespace characters to be equivalent.
-b
Shorthand for "--ignore-space-change".
--ignore-all-space
Ignore whitespace when comparing lines. This ignores differences
even if one line has whitespace where the other line has none.
-w
Shorthand for "--ignore-all-space".
--exit-code
Make the program exit with codes similar to diff(1). That is, it
exits with 1 if there were differences and 0 means no differences.
--quiet
Disable all output of the program. Implies --exit-code.
--ext-diff
Allow an external diff helper to be executed. If you set an
external diff driver with gitattributes(5), you need to use this
option with git-log(1) and friends.
--no-ext-diff
Disallow external diff drivers.
--ignore-submodules
Ignore changes to submodules in the diff generation.
--src-prefix=<prefix>
Show the given source prefix instead of "a/".
--dst-prefix=<prefix>
Show the given destination prefix instead of "b/".
--no-prefix
Do not show any source or destination prefix.
For more detailed explanation on these common options, see also
gitdiffcore(7)[diffcore documentation].
-<n>
Limits the number of patches to prepare.
-o <dir>, --output-directory <dir>
Use <dir> to store the resulting files, instead of the current
working directory.
-n, --numbered
Name output in [PATCH n/m] format.
-N, --no-numbered
Name output in [PATCH] 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.
-s, --signoff
Add Signed-off-by: line to the commit message, using the committer
identity of yourself.
--stdout
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.
--cc=<email>
Add a "Cc:" header to the email headers. This is in addition to any
configured headers, and may be used multiple times.
--cover-letter
Generate a cover letter template. You still have to fill in a
description, but the shortlog and the diffstat will be generated
for you.
--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.
--no-binary
Don´t output contents of changes in binary files, just take note
that they differ. Note that this disable the patch to be properly
applied. By default the contents of changes in those files are
encoded in the patch.
CONFIGURATION
You can specify extra mail header lines to be added to each message in
the repository configuration, new defaults for the subject prefix and
file suffix, and number patches when outputting more than one.
[format]
headers = "Organization: git-foo\n"
subjectprefix = CHANGE
suffix = .txt
numbered = auto
cc = <email>
EXAMPLES
· Extract commits between revisions R1 and R2, and apply them on top
of the current branch using git-am to cherry-pick them:
$ git format-patch -k --stdout R1..R2 | git-am -3 -k
· Extract all commits which are in the current branch but not in the
origin branch:
$ git format-patch origin
For each commit a separate file is created in the current
directory.
· Extract all commits that lead to origin since the inception of the
project:
$ git format-patch \--root origin
· The same as the previous one:
$ git format-patch -M -B origin
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.
· Extract three topmost commits from the current branch and format
them as e-mailable patches:
$ git format-patch -3
SEE ALSO
git-am(1), git-send-email(1)
AUTHOR
Written by Junio C Hamano <junkio@cox.net>
DOCUMENTATION
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
GIT
Part of the git(1) suite