Porcelain level "log" family should recurse when diffing.
[git/git.git] / Documentation / git-format-patch.txt
CommitLineData
215a7ad1
JH
1git-format-patch(1)
2===================
7fc9d69f
JH
3
4NAME
5----
7bd7f280 6git-format-patch - Prepare patches for e-mail submission
7fc9d69f
JH
7
8
9SYNOPSIS
10--------
353ce815 11[verse]
c112f689 12'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--thread]
2d9e4a47 13 [--attach[=<boundary>] | --inline[=<boundary>]]
e6ff0f42
JL
14 [-s | --signoff] [<common diff options>]
15 [--start-number <n>] [--numbered-files]
2d9e4a47
RJ
16 [--in-reply-to=Message-Id] [--suffix=.<sfx>]
17 [--ignore-if-in-upstream]
18 [--subject-prefix=Subject-Prefix]
19 <since>[..<until>]
7fc9d69f
JH
20
21DESCRIPTION
22-----------
2052d146
DS
23
24Prepare each commit between <since> and <until> with its patch in
25one file per commit, formatted to resemble UNIX mailbox format.
26If ..<until> is not specified, the head of the current working
41a5564e
SP
27tree is implied. For a more complete list of ways to spell
28<since> and <until>, see "SPECIFYING REVISIONS" section in
29gitlink:git-rev-parse[1].
2052d146
DS
30
31The output of this command is convenient for e-mail submission or
32for use with gitlink:git-am[1].
35ef3a4c 33
e6ff0f42 34By default, each output file is numbered sequentially from 1, and uses the
2052d146 35first line of the commit message (massaged for pathname safety) as
e6ff0f42
JL
36the filename. With the --numbered-files option, the output file names
37will only be numbers, without the first line of the commit appended.
38The names of the output files are printed to standard
2052d146 39output, unless the --stdout option is specified.
66f04f38 40
2052d146
DS
41If -o is specified, output files are created in <dir>. Otherwise
42they are created in the current working directory.
35ef3a4c 43
2052d146
DS
44If -n is specified, instead of "[PATCH] Subject", the first line
45is formatted as "[PATCH n/m] Subject".
35ef3a4c 46
cc35de84
JT
47If given --thread, git-format-patch will generate In-Reply-To and
48References headers to make the second and subsequent patch mails appear
49as replies to the first mail; this also generates a Message-Id header to
50reference.
7fc9d69f
JH
51
52OPTIONS
53-------
b8105375
BG
54include::diff-options.txt[]
55
ed5f07a6
MV
56-<n>::
57 Limits the number of patches to prepare.
58
6f855371 59-o|--output-directory <dir>::
35ef3a4c 60 Use <dir> to store the resulting files, instead of the
efd02016 61 current working directory.
35ef3a4c 62
6f855371 63-n|--numbered::
35ef3a4c
JH
64 Name output in '[PATCH n/m]' format.
65
2052d146
DS
66--start-number <n>::
67 Start numbering the patches at <n> instead of 1.
68
e6ff0f42
JL
69--numbered-files::
70 Output file names will be a simple number sequence
71 without the default first line of the commit appended.
72 Mutually exclusive with the --stdout option.
73
6f855371 74-k|--keep-subject::
35ef3a4c
JH
75 Do not strip/add '[PATCH]' from the first line of the
76 commit log message.
77
6f855371
NW
78-s|--signoff::
79 Add `Signed-off-by:` line to the commit message, using
80 the committer identity of yourself.
81
54ba6013 82--stdout::
2052d146
DS
83 Print all commits to the standard output in mbox format,
84 instead of creating a file for each one.
7fc9d69f 85
c112f689
JS
86--attach[=<boundary>]::
87 Create multipart/mixed attachment, the first part of
88 which is the commit message and the patch itself in the
89 second part, with "Content-Disposition: attachment".
90
91--inline[=<boundary>]::
92 Create multipart/mixed attachment, the first part of
93 which is the commit message and the patch itself in the
94 second part, with "Content-Disposition: inline".
a15a44ef 95
cc35de84
JT
96--thread::
97 Add In-Reply-To and References headers to make the second and
98 subsequent mails appear as replies to the first. Also generates
99 the Message-Id header to reference.
28ffb898 100
da56645d
JT
101--in-reply-to=Message-Id::
102 Make the first mail (or all the mails with --no-thread) appear as a
103 reply to the given Message-Id, which avoids breaking threads to
104 provide a new patch series.
105
cc75ad67
DK
106--ignore-if-in-upstream::
107 Do not include a patch that matches a commit in
108 <until>..<since>. This will examine all patches reachable
109 from <since> but not from <until> and compare them with the
110 patches being generated, and any patch that matches is
111 ignored.
112
2d9e4a47
RJ
113--subject-prefix=<Subject-Prefix>::
114 Instead of the standard '[PATCH]' prefix in the subject
115 line, instead use '[<Subject-Prefix>]'. This
116 allows for useful naming of a patch series, and can be
117 combined with the --numbered option.
118
03eeaeae 119--suffix=.<sfx>::
917a8f89 120 Instead of using `.patch` as the suffix for generated
02783075 121 filenames, use specified suffix. A common alternative is
917a8f89 122 `--suffix=.txt`.
03eeaeae
JH
123+
124Note that you would need to include the leading dot `.` if you
125want a filename like `0001-description-of-my-change.patch`, and
126the first letter does not have to be a dot. Leaving it empty would
127not add any suffix.
128
96ce6d26
MM
129CONFIGURATION
130-------------
131You can specify extra mail header lines to be added to each
dbd21447
AR
132message in the repository configuration. You can also specify
133new defaults for the subject prefix and file suffix.
96ce6d26 134
917a8f89 135------------
96ce6d26
MM
136[format]
137 headers = "Organization: git-foo\n"
dbd21447 138 subjectprefix = CHANGE
917a8f89
JH
139 suffix = .txt
140------------
03eeaeae 141
96ce6d26 142
28ffb898
JH
143EXAMPLES
144--------
145
146git-format-patch -k --stdout R1..R2 | git-am -3 -k::
147 Extract commits between revisions R1 and R2, and apply
148 them on top of the current branch using `git-am` to
149 cherry-pick them.
150
151git-format-patch origin::
2052d146
DS
152 Extract all commits which are in the current branch but
153 not in the origin branch. For each commit a separate file
154 is created in the current directory.
28ffb898 155
803f498c 156git-format-patch -M -B origin::
2052d146
DS
157 The same as the previous one. Additionally, it detects
158 and handles renames and complete rewrites intelligently to
159 produce a renaming patch. A renaming patch reduces the
160 amount of text output, and generally makes it easier to
161 review it. Note that the "patch" program does not
162 understand renaming patches, so use it only when you know
163 the recipient uses git to apply your patch.
803f498c 164
7c496280
JH
165git-format-patch -3::
166 Extract three topmost commits from the current branch
167 and format them as e-mailable patches.
28ffb898
JH
168
169See Also
170--------
353ce815 171gitlink:git-am[1], gitlink:git-send-email[1]
28ffb898
JH
172
173
7fc9d69f
JH
174Author
175------
176Written by Junio C Hamano <junkio@cox.net>
177
178Documentation
179--------------
180Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
181
182GIT
183---
a7154e91 184Part of the gitlink:git[7] suite