Documentation/git-am.txt: Pass -r in the example invocation of rm -f .dotest
[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]
870e0d61
FL
12'git-am' [--signoff] [--dotest=<dir>] [--keep] [--utf8 | --no-utf8]
13 [--3way] [--interactive] [--binary]
14 [--whitespace=<option>] [-C<n>] [-p<n>]
d63bd9a2 15 <mbox>|<Maildir>...
087b6742 16'git-am' [--skip | --resolved]
42e2cba2
PB
17
18DESCRIPTION
19-----------
20Splits mail messages in a mailbox into commit log message,
21authorship information and patches, and applies them to the
22current branch.
23
baa720f5
JH
24OPTIONS
25-------
d63bd9a2 26<mbox>|<Maildir>...::
d4144612 27 The list of mailbox files to read patches from. If you do not
d63bd9a2
FP
28 supply this argument, reads from the standard input. If you supply
29 directories, they'll be treated as Maildirs.
d4144612 30
5c19f244 31-s, --signoff::
baa720f5
JH
32 Add `Signed-off-by:` line to the commit message, using
33 the committer identity of yourself.
42e2cba2 34
5c19f244 35-d=<dir>, --dotest=<dir>::
baa720f5
JH
36 Instead of `.dotest` directory, use <dir> as a working
37 area to store extracted patches.
42e2cba2 38
5c19f244 39-k, --keep::
5162e697 40 Pass `-k` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]).
d84029b6 41
5c19f244 42-u, --utf8::
5162e697 43 Pass `-u` flag to `git-mailinfo` (see linkgit:git-mailinfo[1]).
d84029b6 44 The proposed commit log message taken from the e-mail
870e0d61 45 is re-coded into UTF-8 encoding (configuration variable
d84029b6
JH
46 `i18n.commitencoding` can be used to specify project's
47 preferred encoding if it is not UTF-8).
48+
49This was optional in prior versions of git, but now it is the
50default. You could use `--no-utf8` to override this.
51
52--no-utf8::
5c19f244 53 Pass `-n` flag to `git-mailinfo` (see
5162e697 54 linkgit:git-mailinfo[1]).
baa720f5 55
5c19f244 56-3, --3way::
baa720f5
JH
57 When the patch does not apply cleanly, fall back on
58 3-way merge, if the patch records the identity of blobs
59 it is supposed to apply to, and we have those blobs
870e0d61 60 available locally.
baa720f5 61
870e0d61
FL
62-b, --binary::
63 Pass `--allow-binary-replacement` flag to `git-apply`
5162e697 64 (see linkgit:git-apply[1]).
baa720f5 65
8273c79a 66--whitespace=<option>::
5162e697 67 This flag is passed to the `git-apply` (see linkgit:git-apply[1])
870e0d61 68 program that applies
8273c79a
JH
69 the patch.
70
2092a1fe 71-C<n>, -p<n>::
5162e697 72 These flags are passed to the `git-apply` (see linkgit:git-apply[1])
870e0d61 73 program that applies
67dad687
MT
74 the patch.
75
5c19f244 76-i, --interactive::
870e0d61
FL
77 Run interactively.
78
79--skip::
80 Skip the current patch. This is only meaningful when
81 restarting an aborted patch.
baa720f5 82
5c19f244 83-r, --resolved::
087b6742
JH
84 After a patch failure (e.g. attempting to apply
85 conflicting patch), the user has applied it by hand and
86 the index file stores the result of the application.
87 Make a commit using the authorship and commit log
88 extracted from the e-mail message and the current index
89 file, and continue.
baa720f5 90
5c19f244
AR
91--resolvemsg=<msg>::
92 When a patch failure occurs, <msg> will be printed
93 to the screen before exiting. This overrides the
94 standard message informing you to use `--resolved`
95 or `--skip` to handle the failure. This is solely
96 for internal use between `git-rebase` and `git-am`.
97
baa720f5
JH
98DISCUSSION
99----------
100
2499857b
JH
101The commit author name is taken from the "From: " line of the
102message, and commit author time is taken from the "Date: " line
103of the message. The "Subject: " line is used as the title of
104the commit, after stripping common prefix "[PATCH <anything>]".
105It is supposed to describe what the commit is about concisely as
106a one line text.
107
108The body of the message (iow, after a blank line that terminates
109RFC2822 headers) can begin with "Subject: " and "From: " lines
110that are different from those of the mail header, to override
111the values of these fields.
112
113The commit message is formed by the title taken from the
114"Subject: ", a blank line and the body of the message up to
115where the patch begins. Excess whitespaces at the end of the
116lines are automatically stripped.
117
118The patch is expected to be inline, directly following the
119message. Any line that is of form:
120
121* three-dashes and end-of-line, or
122* a line that begins with "diff -", or
123* a line that begins with "Index: "
124
125is taken as the beginning of a patch, and the commit log message
126is terminated before the first occurrence of such a line.
127
baa720f5
JH
128When initially invoking it, you give it names of the mailboxes
129to crunch. Upon seeing the first patch that does not apply, it
d45cc6e2 130aborts in the middle,. You can recover from this in one of two ways:
baa720f5 131
870e0d61 132. skip the current patch by re-running the command with '--skip'
baa720f5
JH
133 option.
134
087b6742
JH
135. hand resolve the conflict in the working directory, and update
136 the index file to bring it in a state that the patch should
1e2ccd3a 137 have produced. Then run the command with '--resolved' option.
baa720f5
JH
138
139The command refuses to process new mailboxes while `.dotest`
140directory exists, so if you decide to start over from scratch,
81fa1459 141run `rm -f -r .dotest` before running the command with mailbox
baa720f5 142names.
42e2cba2
PB
143
144
145SEE ALSO
146--------
5162e697 147linkgit:git-apply[1].
42e2cba2
PB
148
149
150Author
151------
152Written by Junio C Hamano <junkio@cox.net>
153
154Documentation
155--------------
156Documentation by Petr Baudis, Junio C Hamano and the git-list <git@vger.kernel.org>.
157
42e2cba2
PB
158GIT
159---
5162e697 160Part of the linkgit:git[7] suite