git-format-patch(1)
git-format-patch(1)
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.
There are two ways to specify which commits to operate on.
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.
Generic <revision range> expression (see "SPECIFYING
REVISIONS" section in ) 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. If you want to format a single commit, you can do
this with "git format-patch -1 <commit>".
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.
By default, the subject of a single patch is "[PATCH] First Line" and
the subject when multiple patches are output is "[PATCH n/m] First
Line". To force 1/1 to be added for a single patch, use -n. To omit
patch numbers from the subject, use -N
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<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".
--patience
Generate a diff using the "patience diff" algorithm.
--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 the distribution of relative amount of changes (number of lines added or
removed) for each sub-directory. Directories with changes below
a cut-off percent (3% by default) are not shown. The cut-off percent
can be set with "--dirstat=limit". Changes in a child directory is not
counted for the parent directory, unless "--cumulative" is used.
--dirstat-by-file[=limit]
Same as --dirstat, but counts changed files instead of lines.
--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[=<regex>]
Show colored word diff, i.e., color words which have changed.
By default, words are separated by whitespace.
When a <regex> is specified, every non-overlapping match of the
<regex> is considered a word. Anything between these matches is
considered whitespace and ignored(!) for the purposes of finding
differences. You may want to append |[^[:space:]] to your regular
expression to make sure that it matches all non-whitespace characters.
A match that contains a newline is silently truncated(!) at the
newline.
The regex can also be set via a diff driver or configuration option, see
or . Giving it explicitly
overrides any diff driver or configuration setting. Diff drivers
override configuration settings.
--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 of characters, show the full
pre- and post-image blob object names on the "index"
line when generating 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 a partial 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 (i.e. regular file, symlink, submodule, …) 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.
-a
--text
Treat all files as text.
--ignore-space-at-eol
Ignore changes in whitespace at EOL.
-b
--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.
-w
--ignore-all-space
Ignore whitespace when comparing lines. This ignores
differences even if one line has whitespace where the other
line has none.
--inter-hunk-context=<lines>
Show the context between diff hunks, up to the specified number
of lines, thereby fusing hunks that are close to each other.
--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 , you need
to use this option with 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
.
-<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, even with a single patch.
-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
In addition to the patches, generate a cover letter file
containing the shortlog and the overall diffstat. You can
fill in a description in the file before sending it out.
--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
,
Author
Written by Junio C Hamano <gitster@pobox.com>
Documentation
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
GIT
Part of the suite