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