SYNOPSIS
--------
[verse]
-'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
- [--attach[=<boundary>] | --inline[=<boundary>] |
- [--no-attach]]
- [-s | --signoff] [<common diff options>]
+'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
+ [--thread[=<style>]]
+ [(--attach|--inline)[=<boundary>] | --no-attach]
+ [-s | --signoff]
[-n | --numbered | -N | --no-numbered]
[--start-number <n>] [--numbered-files]
[--in-reply-to=Message-Id] [--suffix=.<sfx>]
[--subject-prefix=Subject-Prefix]
[--cc=<email>]
[--cover-letter]
+ [<common diff options>]
[ <since> | <revision range> ]
DESCRIPTION
REVISIONS" section in linkgit: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. If you want to format a single commit, you can do
-this with "git format-patch -1 <commit>".
+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 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
+'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'
+`\--in-reply-to`, and the first patch mail, in this order. 'deep'
threading makes every mail a reply to the previous one. If not
specified, defaults to the 'format.thread' configuration, or `shallow`
if that is not set.
Add a "Cc:" header to the email headers. This is in addition
to any configured headers, and may be used multiple times.
+--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"
+
--cover-letter::
In addition to the patches, generate a cover letter file
containing the shortlog and the overall diffstat. You can
--suffix=.<sfx>::
Instead of using `.patch` as the suffix for generated
filenames, use specified suffix. A common alternative is
- `--suffix=.txt`.
+ `--suffix=.txt`. Leaving this empty will remove the `.patch`
+ suffix.
+
-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.
+Note that the leading character does not have to be a dot; for example,
+you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
--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.
+ Do not output contents of changes in binary files, instead
+ display a notice that those files changed. Patches generated
+ using this option cannot be applied properly, but they are
+ still useful for code review.
+
+--root::
+ Treat the revision argument as a <revision range>, even if it
+ is just a single commit (that would normally be treated as a
+ <since>). Note that root commits included in the specified
+ range are always formatted as creation patches, independently
+ of this flag.
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, control attachements, and number patches when outputting
-more than one.
+You can specify extra mail header lines to be added to each message,
+defaults for the subject prefix and file suffix, number patches when
+outputting more than one patch, add "Cc:" headers, configure attachments,
+and sign off patches with configuration variables.
------------
[format]
numbered = auto
cc = <email>
attach [ = mime-boundary-string ]
+ signoff = true
------------
+
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
+the amount of text output, and generally makes it easier to review.
+Note that non-git "patch" programs won't 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