git/Documentation/git-format-patch.adoc

git-format-patch(1)
===================

NAME
----
git-format-patch - Prepare patches for e-mail submission


SYNOPSIS
--------
[verse]
'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
		   [--no-thread | --thread[=<style>]]
		   [(--attach|--inline)[=<boundary>] | --no-attach]
		   [-s | --signoff]
		   [--signature=<signature> | --no-signature]
		   [--signature-file=<file>]
		   [-n | --numbered | -N | --no-numbered]
		   [--start-number <n>] [--numbered-files]
		   [--in-reply-to=<message-id>] [--suffix=.<sfx>]
		   [--ignore-if-in-upstream] [--always]
		   [--cover-from-description=<mode>]
		   [--rfc[=<rfc>]] [--subject-prefix=<subject-prefix>]
		   [(--reroll-count|-v) <n>]
		   [--to=<email>] [--cc=<email>]
		   [--[no-]cover-letter] [--quiet]
		   [--commit-list-format=<format-spec>]
		   [--[no-]encode-email-headers]
		   [--no-notes | --notes[=<ref>]]
		   [--interdiff=<previous>]
		   [--range-diff=<previous> [--creation-factor=<percent>]]
		   [--filename-max-length=<n>]
		   [--progress]
		   [<common-diff-options>]
		   [ <since> | <revision-range> ]

DESCRIPTION
-----------

Prepare each non-merge commit with its "patch" in
one "message" per commit, formatted to resemble a UNIX mailbox.
The output of this command is convenient for e-mail submission or
for use with 'git am'.

A "message" generated by the command consists of three parts:

* A brief metadata header that begins with `From <commit>`
  with a fixed `Mon Sep 17 00:00:00 2001` datestamp to help programs
  like "file(1)" to recognize that the file is an output from this
  command, fields that record the author identity, the author date,
  and the title of the change (taken from the first paragraph of the
  commit log message).

* The second and subsequent paragraphs of the commit log message.

* The "patch", which is the "diff -p --stat" output (see
  linkgit:git-diff[1]) between the commit and its parent.

The log message and the patch are separated by a line with a
three-dash line.

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 linkgit:gitrevisions[7]) means the
   commits in the specified range.

The first rule takes precedence in the case of a single <commit>.  To
apply the second rule, i.e., format everything since the beginning of
history up until <commit>, use the `--root` option: `git format-patch
--root <commit>`.  If you want to format only <commit> itself, 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. The default path
can be set with the `format.outputDirectory` configuration option.
The `-o` option takes precedence over `format.outputDirectory`.
To store patches in the current working directory even when
`format.outputDirectory` points elsewhere, use `-o .`. All directory
components will be created.

By default, the subject of a single patch is "[PATCH] " followed by
the concatenation of lines from the commit message up to the first blank
line (see the DISCUSSION section of linkgit:git-commit[1]).

When multiple patches are output, the subject prefix will instead be
"[PATCH n/m] ".  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
-------
:git-format-patch: 1
include::diff-options.adoc[]

-<n>::
	Prepare patches from the topmost <n> commits.

-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.

-k::
--keep-subject::
	Do not strip/add '[PATCH]' from the first line of the
	commit log message.

-s::
--signoff::
	Add a `Signed-off-by` trailer to the commit message, using
	the committer identity of yourself.
	See the signoff option in linkgit:git-commit[1] for more information.

--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`.

--no-attach::
	Disable the creation of an attachment, overriding the
	configuration setting.

--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[=<style>]::
--no-thread::
	Controls addition of `In-Reply-To` and `References` headers to
	make the second and subsequent mails appear as replies to the
	first.  Also controls generation of the `Message-ID` header to
	reference.
+
The optional <style> argument can be either `shallow` or `deep`.
'shallow' threading makes every mail a reply to the head of the
series, where the head is chosen from the cover letter, the
`--in-reply-to`, and the first patch mail, in this order.  'deep'
threading makes every mail a reply to the previous one.
+
The default is `--no-thread`, unless the `format.thread` configuration
is set.  `--thread` without an argument is equivalent to `--thread=shallow`.
+
Beware that the default for 'git send-email' is to thread emails
itself.  If you want `git format-patch` to take care of threading, you
will want to ensure that threading is disabled for `git send-email`.

--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.

--always::
	Include patches for commits that do not introduce any change,
	which are omitted by default.

--cover-from-description=<mode>::
	Controls which parts of the cover letter will be automatically
	populated using the branch's description.
+
If `<mode>` is `message` or `default`, the cover letter subject will be
populated with placeholder text. The body of the cover letter will be
populated with the branch's description. This is the default mode when
no configuration nor command line option is specified.
+
If `<mode>` is `subject`, the first paragraph of the branch description will
populate the cover letter subject. The remainder of the description will
populate the body of the cover letter.
+
If `<mode>` is `auto`, if the first paragraph of the branch description
is greater than 100 bytes, then the mode will be `message`, otherwise
`subject` will be used.
+
If `<mode>` is `none`, both the cover letter subject and body will be
populated with placeholder text.

--description-file=<file>::
	Use the contents of <file> instead of the branch's description
	for generating the cover letter.

--subject-prefix=<subject-prefix>::
	Instead of the standard '[PATCH]' prefix in the subject
	line, instead use '[<subject-prefix>]'. This can be used
	to name a patch series, and can be combined with the
	`--numbered` option.
+
The configuration variable `format.subjectPrefix` may also be used
to configure a subject prefix to apply to a given repository for
all patches. This is often useful on mailing lists which receive
patches for several repositories and can be used to disambiguate
the patches (with a value of e.g. "PATCH my-project").

--filename-max-length=<n>::
	Instead of the standard 64 bytes, chomp the generated output
	filenames at around '<n>' bytes (too short a value will be
	silently raised to a reasonable length).  Defaults to the
	value of the `format.filenameMaxLength` configuration
	variable, or 64 if unconfigured.

--rfc[=<rfc>]::
	Prepends the string _<rfc>_ (defaults to "RFC") to
	the subject prefix.  As the subject prefix defaults to
	"PATCH", you'll get "RFC PATCH" by default.
+
RFC means "Request For Comments"; use this when sending
an experimental patch for discussion rather than application.
"--rfc=WIP" may also be a useful way to indicate that a patch
is not complete yet ("WIP" stands for "Work In Progress").
+
If the convention of the receiving community for a particular extra
string is to have it _after_ the subject prefix, the string _<rfc>_
can be prefixed with a dash ("`-`") to signal that the rest of
the _<rfc>_ string should be appended to the subject prefix instead,
e.g., `--rfc='-(WIP)'` results in "PATCH (WIP)".

-v <n>::
--reroll-count=<n>::
	Mark the series as the <n>-th iteration of the topic. The
	output filenames have `v<n>` prepended to them, and the
	subject prefix ("PATCH" by default, but configurable via the
	`--subject-prefix` option) has ` v<n>` appended to it.  E.g.
	`--reroll-count=4` may produce `v4-0001-add-makefile.patch`
	file that has "Subject: [PATCH v4 1/20] Add makefile" in it.
	`<n>` does not have to be an integer (e.g. "--reroll-count=4.4",
	or "--reroll-count=4rev2" are allowed), but the downside of
	using such a reroll-count is that the range-diff/interdiff
	with the previous version does not state exactly which
	version the new iteration is compared against.

--to=<email>::
	Add a `To:` header to the email headers. This is in addition
	to any configured headers, and may be used multiple times.
	The negated form `--no-to` discards all `To:` headers added so
	far (from config or command line).

--cc=<email>::
	Add a `Cc:` header to the email headers. This is in addition
	to any configured headers, and may be used multiple times.
	The negated form `--no-cc` discards all `Cc:` headers added so
	far (from config or command line).

--from::
--from=<ident>::
	Use `ident` in the `From:` header of each email. In case of a
	commit email, if the author ident of the commit is not textually
	identical to the provided `ident`, place a `From:` header in the
	body of the message with the original author. If no `ident` is
	given, or if the option is not passed at all, use the ident of
	the current committer.
+
Note that this option is only useful if you are actually sending the
emails and want to identify yourself as the sender, but retain the
original author (and `git am` will correctly pick up the in-body
header). Note also that `git send-email` already handles this
transformation for you, and this option should not be used if you are
feeding the result to `git send-email`.

--force-in-body-from::
--no-force-in-body-from::
	With the e-mail sender specified via the `--from` option, by
	default, an in-body "From:" to identify the real author of
	the commit is added at the top of the commit log message if
	the sender is different from the author.  With this option,
	the in-body "From:" is added even when the sender and the
	author have the same name and address, which may help if the
	mailing list software mangles the sender's identity.
	Defaults to the value of the `format.forceInBodyFrom`
	configuration variable.

--add-header=<header>::
	Add an arbitrary header to the email headers.  This is in addition
	to any configured headers, and may be used multiple times.
	For example, `--add-header="Organization: git-foo"`.
	The negated form `--no-add-header` discards *all* (`To:`,
	`Cc:`, and custom) headers added so far from config or command
	line.

--cover-letter::
--no-cover-letter::
	In addition to the patches, generate a cover letter file containing the
	branch description, commit list and the overall diffstat.  You can fill
	in a description in the file before sending it out.

--commit-list-format=<format-spec>::
	Specify the format in which to generate the commit list of the patch
	series. The accepted values for format-spec are `shortlog`, `modern` or
	a format-string prefixed with `log:`. E.g. `log: %s (%an)`.
	`modern` is the same as `log:%w(72)[%(count)/%(total)] %s`.
	The `log:` prefix can be omitted if the format-string has a `%` in it
	(expecting that it is part of `%<placeholder>`).
	Defaults to the `format.commitListFormat` configuration variable, if
	set, or `shortlog`.
	This option given from the command-line implies the use of
	`--cover-letter` unless `--no-cover-letter` is given.

--encode-email-headers::
--no-encode-email-headers::
	Encode email headers that have non-ASCII characters with
	"Q-encoding" (described in RFC 2047), instead of outputting the
	headers verbatim. Defaults to the value of the
	`format.encodeEmailHeaders` configuration variable.

--interdiff=<previous>::
	As a reviewer aid, insert an interdiff into the cover letter,
	or as commentary of the lone patch of a 1-patch series, showing
	the differences between the previous version of the patch series and
	the series currently being formatted. `previous` is a single revision
	naming the tip of the previous series which shares a common base with
	the series being formatted (for example `git format-patch
	--cover-letter --interdiff=feature/v1 -3 feature/v2`).

--range-diff=<previous>::
	As a reviewer aid, insert a range-diff (see linkgit:git-range-diff[1])
	into the cover letter, or as commentary of the lone patch of a
	1-patch series, showing the differences between the previous
	version of the patch series and the series currently being formatted.
	`previous` can be a single revision naming the tip of the previous
	series if it shares a common base with the series being formatted (for
	example `git format-patch --cover-letter --range-diff=feature/v1 -3
	feature/v2`), or a revision range if the two versions of the series are
	disjoint (for example `git format-patch --cover-letter
	--range-diff=feature/v1~3..feature/v1 -3 feature/v2`).
+
Note that diff options passed to the command affect how the primary
product of `format-patch` is generated, and they are not passed to
the underlying `range-diff` machinery used to generate the cover-letter
material (this may change in the future).

--creation-factor=<percent>::
	Used with `--range-diff`, tweak the heuristic which matches up commits
	between the previous and current series of patches by adjusting the
	creation/deletion cost fudge factor. See linkgit:git-range-diff[1])
	for details.
+
Defaults to 999 (the linkgit:git-range-diff[1] uses 60), as the use
case is to show comparison with an older iteration of the same
topic and the tool should find more correspondence between the two
sets of patches.

--notes[=<ref>]::
--no-notes::
	Append the notes (see linkgit:git-notes[1]) for the commit
	after the three-dash line.
+
The expected use case of this is to write supporting explanation for
the commit that does not belong to the commit log message proper,
and include it with the patch submission. While one can simply write
these explanations after `format-patch` has run but before sending,
keeping them as Git notes allows them to be maintained between versions
of the patch series (but see the discussion of the `notes.rewrite`
configuration options in linkgit:git-notes[1] to use this workflow).
+
The default is `--no-notes`, unless the `format.notes` configuration is
set.

--signature=<signature>::
--no-signature::
	Add a signature to each message produced. Per RFC 3676 the signature
	is separated from the body by a line with '-- ' on it. If the
	signature option is omitted the signature defaults to the Git version
	number.

--signature-file=<file>::
	Works just like --signature except the signature is read from a file.

--suffix=.<sfx>::
	Instead of using `.patch` as the suffix for generated
	filenames, use specified suffix.  A common alternative is
	`--suffix=.txt`.  Leaving this empty will remove the `.patch`
	suffix.
+
Note that the leading character does not have to be a dot; for example,