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