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