Merge branch 'pw/rerere-autoupdate'
[git/git.git] / Documentation / git-am.txt
CommitLineData
42e2cba2 1git-am(1)
05625af3 2=========
42e2cba2
PB
3
4NAME
5----
c3f0baac 6git-am - Apply a series of patches from a mailbox
42e2cba2
PB
7
8
9SYNOPSIS
10--------
353ce815 11[verse]
0460ed2c 12'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8]
e97a5e76 13 [--[no-]3way] [--interactive] [--committer-date-is-author-date]
86c91f91 14 [--ignore-date] [--ignore-space-change | --ignore-whitespace]
b47dfe9e 15 [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
58725efd 16 [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
2dfefe0f 17 [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>]
0adda936 18 [(<mbox> | <Maildir>)...]
9ca488c0 19'git am' (--continue | --skip | --abort | --quit | --show-current-patch)
42e2cba2
PB
20
21DESCRIPTION
22-----------
23Splits mail messages in a mailbox into commit log message,
24authorship information and patches, and applies them to the
25current branch.
26
baa720f5
JH
27OPTIONS
28-------
0adda936 29(<mbox>|<Maildir>)...::
d4144612 30 The list of mailbox files to read patches from. If you do not
07f5746f
DM
31 supply this argument, the command reads from the standard input.
32 If you supply directories, they will be treated as Maildirs.
d4144612 33
3240240f
SB
34-s::
35--signoff::
3db964b5 36 Add a `Signed-off-by:` line to the commit message, using
baa720f5 37 the committer identity of yourself.
b2c150d3 38 See the signoff option in linkgit:git-commit[1] for more information.
42e2cba2 39
3240240f
SB
40-k::
41--keep::
0b444cdb 42 Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
d84029b6 43
f7e5ea17
TR
44--keep-non-patch::
45 Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
46
0460ed2c 47--[no-]keep-cr::
ad2c9280
SH
48 With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1])
49 with the same option, to prevent it from stripping CR at the end of
e80d4cbe
SH
50 lines. `am.keepcr` configuration variable can be used to specify the
51 default behaviour. `--no-keep-cr` is useful to override `am.keepcr`.
ad2c9280 52
017678b4
JH
53-c::
54--scissors::
55 Remove everything in body before a scissors line (see
afb5de7f
MM
56 linkgit:git-mailinfo[1]). Can be activated by default using
57 the `mailinfo.scissors` configuration variable.
017678b4 58
8024d596 59--no-scissors::
434a6db7
NS
60 Ignore scissors lines (see linkgit:git-mailinfo[1]).
61
a078f732
PB
62-m::
63--message-id::
64 Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]),
65 so that the Message-ID header is added to the commit message.
66 The `am.messageid` configuration variable can be used to specify
67 the default behaviour.
68
69--no-message-id::
70 Do not add the Message-ID header to the commit message.
71 `no-message-id` is useful to override `am.messageid`.
72
0e987a12
SB
73-q::
74--quiet::
75 Be quiet. Only print error messages.
76
3240240f
SB
77-u::
78--utf8::
0b444cdb 79 Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
d84029b6 80 The proposed commit log message taken from the e-mail
870e0d61 81 is re-coded into UTF-8 encoding (configuration variable
d84029b6
JH
82 `i18n.commitencoding` can be used to specify project's
83 preferred encoding if it is not UTF-8).
84+
85This was optional in prior versions of git, but now it is the
07f5746f 86default. You can use `--no-utf8` to override this.
d84029b6
JH
87
88--no-utf8::
0b444cdb 89 Pass `-n` flag to 'git mailinfo' (see
5162e697 90 linkgit:git-mailinfo[1]).
baa720f5 91
3240240f
SB
92-3::
93--3way::
e97a5e76 94--no-3way::
baa720f5 95 When the patch does not apply cleanly, fall back on
07f5746f
DM
96 3-way merge if the patch records the identity of blobs
97 it is supposed to apply to and we have those blobs
e97a5e76
RL
98 available locally. `--no-3way` can be used to override
99 am.threeWay configuration variable. For more information,
100 see am.threeWay in linkgit:git-config[1].
baa720f5 101
aba4954c
PW
102--rerere-autoupdate::
103--no-rerere-autoupdate::
104 Allow the rerere mechanism to update the index with the
105 result of auto-conflict resolution if possible.
106
86c91f91
GB
107--ignore-space-change::
108--ignore-whitespace::
8273c79a 109--whitespace=<option>::
3240240f
SB
110-C<n>::
111-p<n>::
b47dfe9e 112--directory=<dir>::
2ae7345a 113--exclude=<path>::
58725efd 114--include=<path>::
b80da424 115--reject::
0b444cdb 116 These flags are passed to the 'git apply' (see linkgit:git-apply[1])
870e0d61 117 program that applies
67dad687
MT
118 the patch.
119
64981376
CP
120--patch-format::
121 By default the command will try to detect the patch format
122 automatically. This option allows the user to bypass the automatic
123 detection and specify the patch format that the patch(es) should be
d9925d1a
EW
124 interpreted as. Valid formats are mbox, mboxrd,
125 stgit, stgit-series and hg.
64981376 126
3240240f
SB
127-i::
128--interactive::
870e0d61
FL
129 Run interactively.
130
a79ec62d
NS
131--committer-date-is-author-date::
132 By default the command records the date from the e-mail
133 message as the commit author date, and uses the time of
134 commit creation as the committer date. This allows the
135 user to lie about the committer date by using the same
e77063fc 136 value as the author date.
a79ec62d
NS
137
138--ignore-date::
139 By default the command records the date from the e-mail
140 message as the commit author date, and uses the time of
141 commit creation as the committer date. This allows the
e77063fc
SB
142 user to lie about the author date by using the same
143 value as the committer date.
a79ec62d 144
870e0d61
FL
145--skip::
146 Skip the current patch. This is only meaningful when
147 restarting an aborted patch.
baa720f5 148
3b4e395f
NV
149-S[<keyid>]::
150--gpg-sign[=<keyid>]::
2b594bf9
MM
151 GPG-sign commits. The `keyid` argument is optional and
152 defaults to the committer identity; if specified, it must be
153 stuck to the option without a space.
3b4e395f 154
c8089af6 155--continue::
3240240f
SB
156-r::
157--resolved::
087b6742
JH
158 After a patch failure (e.g. attempting to apply
159 conflicting patch), the user has applied it by hand and
160 the index file stores the result of the application.
161 Make a commit using the authorship and commit log
162 extracted from the e-mail message and the current index
163 file, and continue.
baa720f5 164
5c19f244
AR
165--resolvemsg=<msg>::
166 When a patch failure occurs, <msg> will be printed
167 to the screen before exiting. This overrides the
8ceb6fbd 168 standard message informing you to use `--continue`
5c19f244 169 or `--skip` to handle the failure. This is solely
0b444cdb 170 for internal use between 'git rebase' and 'git am'.
5c19f244 171
3e5057a8
NS
172--abort::
173 Restore the original branch and abort the patching operation.
174
65ed8ff3
NTND
175--quit::
176 Abort the patching operation but keep HEAD and the index
177 untouched.
178
984913a2
NTND
179--show-current-patch::
180 Show the patch being applied when "git am" is stopped because
181 of conflicts.
182
baa720f5
JH
183DISCUSSION
184----------
185
2499857b 186The commit author name is taken from the "From: " line of the
e77063fc 187message, and commit author date is taken from the "Date: " line
2499857b
JH
188of the message. The "Subject: " line is used as the title of
189the commit, after stripping common prefix "[PATCH <anything>]".
3db964b5
SB
190The "Subject: " line is supposed to concisely describe what the
191commit is about in one line of text.
2499857b 192
f43c97f5
NS
193"From: " and "Subject: " lines starting the body override the respective
194commit author name and title values taken from the headers.
2499857b
JH
195
196The commit message is formed by the title taken from the
197"Subject: ", a blank line and the body of the message up to
3db964b5
SB
198where the patch begins. Excess whitespace at the end of each
199line is automatically stripped.
2499857b
JH
200
201The patch is expected to be inline, directly following the
07f5746f 202message. Any line that is of the form:
2499857b
JH
203
204* three-dashes and end-of-line, or
205* a line that begins with "diff -", or
206* a line that begins with "Index: "
207
208is taken as the beginning of a patch, and the commit log message
209is terminated before the first occurrence of such a line.
210
3db964b5 211When initially invoking `git am`, you give it the names of the mailboxes
07f5746f
DM
212to process. Upon seeing the first patch that does not apply, it
213aborts in the middle. You can recover from this in one of two ways:
baa720f5 214
bcf9626a 215. skip the current patch by re-running the command with the `--skip`
baa720f5
JH
216 option.
217
087b6742 218. hand resolve the conflict in the working directory, and update
07f5746f 219 the index file to bring it into a state that the patch should
bcf9626a 220 have produced. Then run the command with the `--continue` option.
baa720f5 221
b5f306fb
SG
222The command refuses to process new mailboxes until the current
223operation is finished, so if you decide to start over from scratch,
224run `git am --abort` before running the command with mailbox
baa720f5 225names.
42e2cba2 226
9869099b
BG
227Before any patches are applied, ORIG_HEAD is set to the tip of the
228current branch. This is useful if you have problems with multiple
229commits, like running 'git am' on the wrong branch or an error in the
230commits that is more easily fixed by changing the mailbox (e.g.
231errors in the "From:" lines).
232
0e3d40c6
JN
233HOOKS
234-----
235This command can run `applypatch-msg`, `pre-applypatch`,
236and `post-applypatch` hooks. See linkgit:githooks[5] for more
237information.
42e2cba2
PB
238
239SEE ALSO
240--------
5162e697 241linkgit:git-apply[1].
42e2cba2 242
42e2cba2
PB
243GIT
244---
9e1f0a85 245Part of the linkgit:git[1] suite