blob: 69d5cc9f21082569f8614fe47f3e1c0615e21850 [file] [log] [blame]
Petr Baudis42e2cba2005-10-21 02:28:42 +02001git-am(1)
Junio C Hamano05625af2005-10-21 20:57:34 -07002=========
Petr Baudis42e2cba2005-10-21 02:28:42 +02003
4NAME
5----
Junio C Hamanoc3f0baa2007-01-18 15:53:37 -08006git-am - Apply a series of patches from a mailbox
Petr Baudis42e2cba2005-10-21 02:28:42 +02007
8
9SYNOPSIS
10--------
Jonas Fonseca353ce812005-12-31 18:37:15 +010011[verse]
Thierry Reding566902f2022-11-30 18:28:33 +010012'git am' [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--no-verify]
Remi Lespinete97a5e72015-08-04 22:19:26 +080013 [--[no-]3way] [--interactive] [--committer-date-is-author-date]
Giuseppe Bilotta86c91f92009-08-04 13:16:49 +020014 [--ignore-date] [--ignore-space-change | --ignore-whitespace]
Junio C Hamano14d569b2023-10-18 16:35:06 -070015 [--whitespace=<action>] [-C<n>] [-p<n>] [--directory=<dir>]
Johannes Berg58725ef2012-03-28 13:11:28 +020016 [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
Junio C Hamano2dfefe02014-03-25 11:01:31 -070017 [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>]
Đoàn Trần Công Danh59b519a2021-05-10 00:12:13 +070018 [--quoted-cr=<action>]
徐沛文 (Aleen)7c096b82021-12-09 07:25:54 +000019 [--empty=(stop|drop|keep)]
Štěpán Němec0adda932010-10-08 19:31:17 +020020 [(<mbox> | <Maildir>)...]
Jeff King53ce2e32024-06-06 04:21:14 -040021'git am' (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)
Petr Baudis42e2cba2005-10-21 02:28:42 +020022
23DESCRIPTION
24-----------
Elijah Newren6cc668c2023-10-08 06:45:14 +000025Splits mail messages in a mailbox into commit log messages,
Elijah Newren4d542682023-10-08 06:45:24 +000026authorship information, and patches, and applies them to the
Junio C Hamano9b0c7f32023-03-21 10:27:08 -070027current branch. You could think of it as a reverse operation
28of linkgit:git-format-patch[1] run on a branch with a straight
29history without merges.
Petr Baudis42e2cba2005-10-21 02:28:42 +020030
Junio C Hamanobaa720f2005-10-20 22:14:14 -070031OPTIONS
32-------
Štěpán Němec0adda932010-10-08 19:31:17 +020033(<mbox>|<Maildir>)...::
Michael S. Tsirkind4144612007-02-09 12:23:23 +020034 The list of mailbox files to read patches from. If you do not
David J. Mellor07f57462009-03-01 22:37:41 -080035 supply this argument, the command reads from the standard input.
36 If you supply directories, they will be treated as Maildirs.
Michael S. Tsirkind4144612007-02-09 12:23:23 +020037
Stephan Beyer32402402008-06-08 03:36:09 +020038-s::
39--signoff::
Bradley M. Kuhn3abd4a62020-10-19 18:03:55 -070040 Add a `Signed-off-by` trailer to the commit message, using
Junio C Hamanobaa720f2005-10-20 22:14:14 -070041 the committer identity of yourself.
David A. Wheelerb2c150d2016-01-05 14:20:26 -050042 See the signoff option in linkgit:git-commit[1] for more information.
Junio C Hamanobaa720f2005-10-20 22:14:14 -070043
Stephan Beyer32402402008-06-08 03:36:09 +020044-k::
45--keep::
Thomas Rast0b444cd2010-01-10 00:33:00 +010046 Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
Junio C Hamanod84029b2007-01-08 13:59:15 -080047
Thomas Rastf7e5ea12012-01-16 11:53:00 +010048--keep-non-patch::
49 Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
50
Felipe Contreras0460ed22013-05-08 20:16:55 -050051--[no-]keep-cr::
Stefan-W. Hahnad2c9282010-02-27 15:20:26 +010052 With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1])
53 with the same option, to prevent it from stripping CR at the end of
Stefan-W. Hahne80d4cb2010-02-27 15:20:27 +010054 lines. `am.keepcr` configuration variable can be used to specify the
55 default behaviour. `--no-keep-cr` is useful to override `am.keepcr`.
Stefan-W. Hahnad2c9282010-02-27 15:20:26 +010056
Junio C Hamano017678b2009-08-26 21:36:05 -070057-c::
58--scissors::
59 Remove everything in body before a scissors line (see
Matthieu Moyafb5de72015-02-20 20:32:21 +010060 linkgit:git-mailinfo[1]). Can be activated by default using
61 the `mailinfo.scissors` configuration variable.
Junio C Hamano017678b2009-08-26 21:36:05 -070062
Michal Sojka8024d592010-03-04 13:08:28 +010063--no-scissors::
Nicolas Sebrecht434a6db2009-09-11 02:29:58 +020064 Ignore scissors lines (see linkgit:git-mailinfo[1]).
65
Đoàn Trần Công Danh59b519a2021-05-10 00:12:13 +070066--quoted-cr=<action>::
67 This flag will be passed down to 'git mailinfo' (see linkgit:git-mailinfo[1]).
68
Brian Lyles64a443e2024-03-25 18:16:49 -050069--empty=(drop|keep|stop)::
70 How to handle an e-mail message lacking a patch:
71+
72--
73`drop`;;
74 The e-mail message will be skipped.
75`keep`;;
76 An empty commit will be created, with the contents of the e-mail
77 message as its log.
78`stop`;;
79 The command will fail, stopping in the middle of the current `am`
80 session. This is the default behavior.
81--
徐沛文 (Aleen)7c096b82021-12-09 07:25:54 +000082
Paolo Bonzinia078f732014-11-25 15:00:56 +010083-m::
84--message-id::
85 Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]),
86 so that the Message-ID header is added to the commit message.
87 The `am.messageid` configuration variable can be used to specify
88 the default behaviour.
89
90--no-message-id::
91 Do not add the Message-ID header to the commit message.
92 `no-message-id` is useful to override `am.messageid`.
93
Stephen Boyd0e987a12009-06-16 15:33:01 -070094-q::
95--quiet::
96 Be quiet. Only print error messages.
97
Stephan Beyer32402402008-06-08 03:36:09 +020098-u::
99--utf8::
Thomas Rast0b444cd2010-01-10 00:33:00 +0100100 Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]).
Junio C Hamanod84029b2007-01-08 13:59:15 -0800101 The proposed commit log message taken from the e-mail
Frank Lichtenheld870e0d62007-05-14 16:44:53 +0200102 is re-coded into UTF-8 encoding (configuration variable
Elijah Newren0a4f0512023-10-08 06:45:17 +0000103 `i18n.commitEncoding` can be used to specify the project's
Junio C Hamanod84029b2007-01-08 13:59:15 -0800104 preferred encoding if it is not UTF-8).
105+
106This was optional in prior versions of git, but now it is the
David J. Mellor07f57462009-03-01 22:37:41 -0800107default. You can use `--no-utf8` to override this.
Junio C Hamanod84029b2007-01-08 13:59:15 -0800108
109--no-utf8::
Thomas Rast0b444cd2010-01-10 00:33:00 +0100110 Pass `-n` flag to 'git mailinfo' (see
Dan McGee5162e692007-12-29 00:20:38 -0600111 linkgit:git-mailinfo[1]).
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700112
Stephan Beyer32402402008-06-08 03:36:09 +0200113-3::
114--3way::
Remi Lespinete97a5e72015-08-04 22:19:26 +0800115--no-3way::
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700116 When the patch does not apply cleanly, fall back on
David J. Mellor07f57462009-03-01 22:37:41 -0800117 3-way merge if the patch records the identity of blobs
118 it is supposed to apply to and we have those blobs
Remi Lespinete97a5e72015-08-04 22:19:26 +0800119 available locally. `--no-3way` can be used to override
120 am.threeWay configuration variable. For more information,
121 see am.threeWay in linkgit:git-config[1].
Frank Lichtenheld870e0d62007-05-14 16:44:53 +0200122
Junio C Hamano0dbc7152022-07-15 14:32:18 -0700123include::rerere-options.txt[]
Phillip Woodaba49542019-03-14 19:12:32 +0000124
Giuseppe Bilotta86c91f92009-08-04 13:16:49 +0200125--ignore-space-change::
126--ignore-whitespace::
Junio C Hamano14d569b2023-10-18 16:35:06 -0700127--whitespace=<action>::
Stephan Beyer32402402008-06-08 03:36:09 +0200128-C<n>::
129-p<n>::
Junio C Hamanob47dfe92009-01-11 22:21:48 -0800130--directory=<dir>::
maximilian attems2ae73452011-08-09 17:21:08 +0200131--exclude=<path>::
Johannes Berg58725ef2012-03-28 13:11:28 +0200132--include=<path>::
martin f. krafftb80da422009-01-23 11:31:21 +1100133--reject::
Thomas Rast0b444cd2010-01-10 00:33:00 +0100134 These flags are passed to the 'git apply' (see linkgit:git-apply[1])
Frank Lichtenheld870e0d62007-05-14 16:44:53 +0200135 program that applies
136 the patch.
Junio C Hamanoa171dac2024-02-14 10:44:01 -0800137+
138Valid <action> for the `--whitespace` option are:
139`nowarn`, `warn`, `fix`, `error`, and `error-all`.
Frank Lichtenheld870e0d62007-05-14 16:44:53 +0200140
Chris Packham64981372014-03-11 16:51:57 +1300141--patch-format::
142 By default the command will try to detect the patch format
143 automatically. This option allows the user to bypass the automatic
144 detection and specify the patch format that the patch(es) should be
Eric Wongd9925d12016-06-05 04:46:41 +0000145 interpreted as. Valid formats are mbox, mboxrd,
Elijah Newren4d542682023-10-08 06:45:24 +0000146 stgit, stgit-series, and hg.
Chris Packham64981372014-03-11 16:51:57 +1300147
Stephan Beyer32402402008-06-08 03:36:09 +0200148-i::
149--interactive::
Frank Lichtenheld870e0d62007-05-14 16:44:53 +0200150 Run interactively.
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700151
Thierry Reding566902f2022-11-30 18:28:33 +0100152-n::
153--no-verify::
154 By default, the pre-applypatch and applypatch-msg hooks are run.
155 When any of `--no-verify` or `-n` is given, these are bypassed.
156 See also linkgit:githooks[5].
157
Nanako Shiraishia79ec622009-01-24 10:18:02 +0900158--committer-date-is-author-date::
159 By default the command records the date from the e-mail
160 message as the commit author date, and uses the time of
161 commit creation as the committer date. This allows the
162 user to lie about the committer date by using the same
Stephen Boyde77063f2009-05-04 22:19:00 -0700163 value as the author date.
Nanako Shiraishia79ec622009-01-24 10:18:02 +0900164
165--ignore-date::
166 By default the command records the date from the e-mail
167 message as the commit author date, and uses the time of
168 commit creation as the committer date. This allows the
Stephen Boyde77063f2009-05-04 22:19:00 -0700169 user to lie about the author date by using the same
170 value as the committer date.
Nanako Shiraishia79ec622009-01-24 10:18:02 +0900171
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700172--skip::
173 Skip the current patch. This is only meaningful when
174 restarting an aborted patch.
175
Nicolas Vigier3b4e395f2014-02-01 02:18:01 +0000176-S[<keyid>]::
177--gpg-sign[=<keyid>]::
Đoàn Trần Công Danhae06ba62020-04-03 17:28:04 +0700178--no-gpg-sign::
Matthieu Moy2b594bf2015-09-19 09:47:50 +0200179 GPG-sign commits. The `keyid` argument is optional and
180 defaults to the committer identity; if specified, it must be
Đoàn Trần Công Danhae06ba62020-04-03 17:28:04 +0700181 stuck to the option without a space. `--no-gpg-sign` is useful to
182 countermand both `commit.gpgSign` configuration variable, and
183 earlier `--gpg-sign`.
Nicolas Vigier3b4e395f2014-02-01 02:18:01 +0000184
Jeff Kingc8089af2010-02-11 17:27:14 -0500185--continue::
Stephan Beyer32402402008-06-08 03:36:09 +0200186-r::
187--resolved::
Junio C Hamano087b6742005-11-16 16:46:24 -0800188 After a patch failure (e.g. attempting to apply
189 conflicting patch), the user has applied it by hand and
190 the index file stores the result of the application.
191 Make a commit using the authorship and commit log
192 extracted from the e-mail message and the current index
193 file, and continue.
Petr Baudis42e2cba2005-10-21 02:28:42 +0200194
Andrew Ruder5c19f242007-04-16 02:21:31 -0500195--resolvemsg=<msg>::
196 When a patch failure occurs, <msg> will be printed
197 to the screen before exiting. This overrides the
Kevin Bracey8ceb6fb2013-06-26 23:06:41 +0300198 standard message informing you to use `--continue`
Andrew Ruder5c19f242007-04-16 02:21:31 -0500199 or `--skip` to handle the failure. This is solely
Thomas Rast0b444cd2010-01-10 00:33:00 +0100200 for internal use between 'git rebase' and 'git am'.
Andrew Ruder5c19f242007-04-16 02:21:31 -0500201
Nanako Shiraishi3e5057a2008-07-16 19:39:10 +0900202--abort::
203 Restore the original branch and abort the patching operation.
Elijah Newren0a4f0512023-10-08 06:45:17 +0000204 Revert the contents of files involved in the am operation to their
Elijah Newrenea7dc012021-09-10 10:31:14 +0000205 pre-am state.
Nanako Shiraishi3e5057a2008-07-16 19:39:10 +0900206
Nguyễn Thái Ngọc Duy65ed8ff2018-02-14 18:16:06 +0700207--quit::
208 Abort the patching operation but keep HEAD and the index
209 untouched.
210
Jeff King53ce2e32024-06-06 04:21:14 -0400211--retry::
212 Try to apply the last conflicting patch again. This is generally
213 only useful for passing extra options to the retry attempt
214 (e.g., `--3way`), since otherwise you'll just see the same
215 failure again.
216
Paolo Bonziniaa416b22020-02-20 15:15:19 +0100217--show-current-patch[=(diff|raw)]::
218 Show the message at which `git am` has stopped due to
219 conflicts. If `raw` is specified, show the raw contents of
220 the e-mail message; if `diff`, show the diff portion only.
221 Defaults to `raw`.
Nguyễn Thái Ngọc Duy984913a2018-02-11 16:43:26 +0700222
徐沛文 (Aleen)9e7e41b2021-12-09 07:25:55 +0000223--allow-empty::
224 After a patch failure on an input e-mail message lacking a patch,
225 create an empty commit with the contents of the e-mail message
226 as its log message.
227
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700228DISCUSSION
229----------
230
Junio C Hamano24998572007-03-24 03:08:54 -0700231The commit author name is taken from the "From: " line of the
Stephen Boyde77063f2009-05-04 22:19:00 -0700232message, and commit author date is taken from the "Date: " line
Junio C Hamano24998572007-03-24 03:08:54 -0700233of the message. The "Subject: " line is used as the title of
234the commit, after stripping common prefix "[PATCH <anything>]".
Stephen Boyd3db964b2009-05-04 22:18:42 -0700235The "Subject: " line is supposed to concisely describe what the
236commit is about in one line of text.
Junio C Hamano24998572007-03-24 03:08:54 -0700237
Paul Menzelf8740c52020-01-03 16:05:46 +0100238"From: ", "Date: ", and "Subject: " lines starting the body override the
239respective commit author name and title values taken from the headers.
Junio C Hamano24998572007-03-24 03:08:54 -0700240
241The commit message is formed by the title taken from the
242"Subject: ", a blank line and the body of the message up to
Stephen Boyd3db964b2009-05-04 22:18:42 -0700243where the patch begins. Excess whitespace at the end of each
244line is automatically stripped.
Junio C Hamano24998572007-03-24 03:08:54 -0700245
246The patch is expected to be inline, directly following the
David J. Mellor07f57462009-03-01 22:37:41 -0800247message. Any line that is of the form:
Junio C Hamano24998572007-03-24 03:08:54 -0700248
249* three-dashes and end-of-line, or
250* a line that begins with "diff -", or
251* a line that begins with "Index: "
252
253is taken as the beginning of a patch, and the commit log message
254is terminated before the first occurrence of such a line.
255
Stephen Boyd3db964b2009-05-04 22:18:42 -0700256When initially invoking `git am`, you give it the names of the mailboxes
David J. Mellor07f57462009-03-01 22:37:41 -0800257to process. Upon seeing the first patch that does not apply, it
258aborts in the middle. You can recover from this in one of two ways:
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700259
Matthieu Moybcf96262016-06-28 13:40:11 +0200260. skip the current patch by re-running the command with the `--skip`
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700261 option.
262
Junio C Hamano087b6742005-11-16 16:46:24 -0800263. hand resolve the conflict in the working directory, and update
David J. Mellor07f57462009-03-01 22:37:41 -0800264 the index file to bring it into a state that the patch should
Matthieu Moybcf96262016-06-28 13:40:11 +0200265 have produced. Then run the command with the `--continue` option.
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700266
SZEDER Gáborb5f306f2011-03-22 19:42:25 +0100267The command refuses to process new mailboxes until the current
268operation is finished, so if you decide to start over from scratch,
269run `git am --abort` before running the command with mailbox
Junio C Hamanobaa720f2005-10-20 22:14:14 -0700270names.
Petr Baudis42e2cba2005-10-21 02:28:42 +0200271
Brian Gernhardt98690992008-07-08 00:12:22 -0400272Before any patches are applied, ORIG_HEAD is set to the tip of the
273current branch. This is useful if you have problems with multiple
274commits, like running 'git am' on the wrong branch or an error in the
275commits that is more easily fixed by changing the mailbox (e.g.
276errors in the "From:" lines).
277
Jonathan Nieder0e3d40c2014-02-24 12:38:29 -0800278HOOKS
279-----
280This command can run `applypatch-msg`, `pre-applypatch`,
281and `post-applypatch` hooks. See linkgit:githooks[5] for more
282information.
Petr Baudis42e2cba2005-10-21 02:28:42 +0200283
Ævar Arnfjörð Bjarmason16f6b0d2022-09-07 10:27:04 +0200284CONFIGURATION
285-------------
286
287include::includes/cmd-config-section-all.txt[]
288
289include::config/am.txt[]
290
Petr Baudis42e2cba2005-10-21 02:28:42 +0200291SEE ALSO
292--------
Junio C Hamano9b0c7f32023-03-21 10:27:08 -0700293linkgit:git-apply[1],
294linkgit:git-format-patch[1].
Petr Baudis42e2cba2005-10-21 02:28:42 +0200295
Petr Baudis42e2cba2005-10-21 02:28:42 +0200296GIT
297---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200298Part of the linkgit:git[1] suite