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