git-format-patch -3
[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
JH
83--suffix=.<sfx>::
84 Instead of using `.txt` as the suffix for generated
85 filenames, use specifed suffix. A common alternative is
86 `--suffix=.patch`.
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
96message in the repository configuration as follows:
97
98[format]
99 headers = "Organization: git-foo\n"
100
03eeaeae
JH
101You can specify default suffix used:
102
103[format]
104 suffix = .patch
105
96ce6d26 106
28ffb898
JH
107EXAMPLES
108--------
109
110git-format-patch -k --stdout R1..R2 | git-am -3 -k::
111 Extract commits between revisions R1 and R2, and apply
112 them on top of the current branch using `git-am` to
113 cherry-pick them.
114
115git-format-patch origin::
2052d146
DS
116 Extract all commits which are in the current branch but
117 not in the origin branch. For each commit a separate file
118 is created in the current directory.
28ffb898 119
803f498c 120git-format-patch -M -B origin::
2052d146
DS
121 The same as the previous one. Additionally, it detects
122 and handles renames and complete rewrites intelligently to
123 produce a renaming patch. A renaming patch reduces the
124 amount of text output, and generally makes it easier to
125 review it. Note that the "patch" program does not
126 understand renaming patches, so use it only when you know
127 the recipient uses git to apply your patch.
803f498c 128
7c496280
JH
129git-format-patch -3::
130 Extract three topmost commits from the current branch
131 and format them as e-mailable patches.
28ffb898
JH
132
133See Also
134--------
353ce815 135gitlink:git-am[1], gitlink:git-send-email[1]
28ffb898
JH
136
137
7fc9d69f
JH
138Author
139------
140Written by Junio C Hamano <junkio@cox.net>
141
142Documentation
143--------------
144Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
145
146GIT
147---
a7154e91 148Part of the gitlink:git[7] suite
7fc9d69f 149