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