Merge branch 'pw/rerere-autoupdate'
[git/git.git] / Documentation / git-am.txt
1 git-am(1)
2 =========
3
4 NAME
5 ----
6 git-am - Apply a series of patches from a mailbox
7
8
9 SYNOPSIS
10 --------
11 [verse]
12 'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8]
13 [--[no-]3way] [--interactive] [--committer-date-is-author-date]
14 [--ignore-date] [--ignore-space-change | --ignore-whitespace]
15 [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
16 [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
17 [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>]
18 [(<mbox> | <Maildir>)...]
19 'git am' (--continue | --skip | --abort | --quit | --show-current-patch)
20
21 DESCRIPTION
22 -----------
23 Splits mail messages in a mailbox into commit log message,
24 authorship information and patches, and applies them to the
25 current branch.
26
27 OPTIONS
28 -------
29 (<mbox>|<Maildir>)...::
30 The list of mailbox files to read patches from. If you do not
31 supply this argument, the command reads from the standard input.
32 If you supply directories, they will be treated as Maildirs.
33
34 -s::
35 --signoff::
36 Add a `Signed-off-by:` line to the commit message, using
37 the committer identity of yourself.
38 See the signoff option in linkgit:git-commit[1] for more information.
39
40 -k::
41 --keep::
42 Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
43
44 --keep-non-patch::
45 Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
46
47 --[no-]keep-cr::
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
50 lines. `am.keepcr` configuration variable can be used to specify the
51 default behaviour. `--no-keep-cr` is useful to override `am.keepcr`.
52
53 -c::
54 --scissors::
55 Remove everything in body before a scissors line (see
56 linkgit:git-mailinfo[1]). Can be activated by default using
57 the `mailinfo.scissors` configuration variable.
58
59 --no-scissors::
60 Ignore scissors lines (see linkgit:git-mailinfo[1]).
61
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
73 -q::
74 --quiet::
75 Be quiet. Only print error messages.
76
77 -u::
78 --utf8::
79 Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
80 The proposed commit log message taken from the e-mail
81 is re-coded into UTF-8 encoding (configuration variable
82 `i18n.commitencoding` can be used to specify project's
83 preferred encoding if it is not UTF-8).
84 +
85 This was optional in prior versions of git, but now it is the
86 default. You can use `--no-utf8` to override this.
87
88 --no-utf8::
89 Pass `-n` flag to 'git mailinfo' (see
90 linkgit:git-mailinfo[1]).
91
92 -3::
93 --3way::
94 --no-3way::
95 When the patch does not apply cleanly, fall back on
96 3-way merge if the patch records the identity of blobs
97 it is supposed to apply to and we have those blobs
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].
101
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
107 --ignore-space-change::
108 --ignore-whitespace::
109 --whitespace=<option>::
110 -C<n>::
111 -p<n>::
112 --directory=<dir>::
113 --exclude=<path>::
114 --include=<path>::
115 --reject::
116 These flags are passed to the 'git apply' (see linkgit:git-apply[1])
117 program that applies
118 the patch.
119
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
124 interpreted as. Valid formats are mbox, mboxrd,
125 stgit, stgit-series and hg.
126
127 -i::
128 --interactive::
129 Run interactively.
130
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
136 value as the author date.
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
142 user to lie about the author date by using the same
143 value as the committer date.
144
145 --skip::
146 Skip the current patch. This is only meaningful when
147 restarting an aborted patch.
148
149 -S[<keyid>]::
150 --gpg-sign[=<keyid>]::
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.
154
155 --continue::
156 -r::
157 --resolved::
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.
164
165 --resolvemsg=<msg>::
166 When a patch failure occurs, <msg> will be printed
167 to the screen before exiting. This overrides the
168 standard message informing you to use `--continue`
169 or `--skip` to handle the failure. This is solely
170 for internal use between 'git rebase' and 'git am'.
171
172 --abort::
173 Restore the original branch and abort the patching operation.
174
175 --quit::
176 Abort the patching operation but keep HEAD and the index
177 untouched.
178
179 --show-current-patch::
180 Show the patch being applied when "git am" is stopped because
181 of conflicts.
182
183 DISCUSSION
184 ----------
185
186 The commit author name is taken from the "From: " line of the
187 message, and commit author date is taken from the "Date: " line
188 of the message. The "Subject: " line is used as the title of
189 the commit, after stripping common prefix "[PATCH <anything>]".
190 The "Subject: " line is supposed to concisely describe what the
191 commit is about in one line of text.
192
193 "From: " and "Subject: " lines starting the body override the respective
194 commit author name and title values taken from the headers.
195
196 The commit message is formed by the title taken from the
197 "Subject: ", a blank line and the body of the message up to
198 where the patch begins. Excess whitespace at the end of each
199 line is automatically stripped.
200
201 The patch is expected to be inline, directly following the
202 message. Any line that is of the form:
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
208 is taken as the beginning of a patch, and the commit log message
209 is terminated before the first occurrence of such a line.
210
211 When initially invoking `git am`, you give it the names of the mailboxes
212 to process. Upon seeing the first patch that does not apply, it
213 aborts in the middle. You can recover from this in one of two ways:
214
215 . skip the current patch by re-running the command with the `--skip`
216 option.
217
218 . hand resolve the conflict in the working directory, and update
219 the index file to bring it into a state that the patch should
220 have produced. Then run the command with the `--continue` option.
221
222 The command refuses to process new mailboxes until the current
223 operation is finished, so if you decide to start over from scratch,
224 run `git am --abort` before running the command with mailbox
225 names.
226
227 Before any patches are applied, ORIG_HEAD is set to the tip of the
228 current branch. This is useful if you have problems with multiple
229 commits, like running 'git am' on the wrong branch or an error in the
230 commits that is more easily fixed by changing the mailbox (e.g.
231 errors in the "From:" lines).
232
233 HOOKS
234 -----
235 This command can run `applypatch-msg`, `pre-applypatch`,
236 and `post-applypatch` hooks. See linkgit:githooks[5] for more
237 information.
238
239 SEE ALSO
240 --------
241 linkgit:git-apply[1].
242
243 GIT
244 ---
245 Part of the linkgit:git[1] suite