git-am - Man Page

• Apply and commit changes following a local patch file: git am path/to/file.patch
• Apply and commit changes following a remote patch file: curl [-L|--location] https://example.com/file.patch | git am
• Abort the process of applying a patch file: git am --abort
• Apply as much of a patch file as possible, saving failed hunks to reject files: git am --reject path/to/file.patch

tldr.sh

git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8] [--[no-]verify]
	 [--[no-]3way] [--interactive] [--committer-date-is-author-date]
	 [--ignore-date] [--ignore-space-change | --ignore-whitespace]
	 [--whitespace=<action>] [-C<n>] [-p<n>] [--directory=<dir>]
	 [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
	 [--[no-]scissors] [-S[<key-id>]] [--patch-format=<format>]
	 [--quoted-cr=<action>]
	 [--empty=(stop|drop|keep)]
	 [(<mbox> | <Maildir>)​...]
git am (--continue | --skip | --abort | --quit | --retry | --show-current-patch[=(diff|raw)] | --allow-empty)

Splits mail messages in a mailbox into commit log messages, authorship information, and patches, and applies them to the current branch​. You could think of it as a reverse operation of git-format-patch(1) run on a branch with a straight history without merges​.

(<mbox>|<Maildir>)​.​.​.

The list of mailbox files to read patches from​. If you do not supply this argument, the command reads from the standard input​. If you supply directories, they will be treated as Maildirs​.

-s,  --signoff

Add a Signed-off-by trailer to the commit message (see git-interpret-trailers(1)), using the committer identity of yourself​. See the signoff option in git-commit(1) for more information​.

-k,  --keep

Pass -k flag to git-mailinfo(1)​.

--keep-non-patch

Pass -b flag to git-mailinfo(1)​.

--keep-cr,  --no-keep-cr

With --keep-cr, call git-mailsplit(1) with the same option, to prevent it from stripping CR at the end of lines​. am​.keepcr configuration variable can be used to specify the default behaviour​. --no-keep-cr is useful to override am​.keepcr​.

-c,  --scissors

Remove everything in body before a scissors line (see git-mailinfo(1))​. Can be activated by default using the mailinfo​.scissors configuration variable​.

--no-scissors

Ignore scissors lines (see git-mailinfo(1))​.

--quoted-cr=<action>

This flag will be passed down to git-mailinfo(1)​.

--empty=(drop|keep|stop)

How to handle an e-mail message lacking a patch:

drop

The e-mail message will be skipped​.

keep

An empty commit will be created, with the contents of the e-mail message as its log​.

stop

The command will fail, stopping in the middle of the current am session​. This is the default behavior​.

-m,  --message-id

Pass the -m flag to git-mailinfo(1), so that the Message-ID header is added to the commit message​. The am​.messageid configuration variable can be used to specify the default behaviour​.

--no-message-id

Do not add the Message-ID header to the commit message​. --no-message-id is useful to override am​.messageid​.

-q,  --quiet

Be quiet​. Only print error messages​.

-u,  --utf8

Pass -u flag to git-mailinfo(1)​. The proposed commit log message taken from the e-mail is re-coded into UTF-8 encoding (configuration variable i18n​.commitEncoding can be used to specify the project’s preferred encoding if it is not UTF-8)​.

This was optional in prior versions of git, but now it is the default​. You can use --no-utf8 to override this​.

--no-utf8

Pass -n flag to git-mailinfo(1)​.

-3,  --3way,  --no-3way

When the patch does not apply cleanly, fall back on 3-way merge if the patch records the identity of blobs it is supposed to apply to and we have those blobs available locally​. --no-3way can be used to override am​.threeWay configuration variable​. For more information, see am​.threeWay in git-config(1)​.

--rerere-autoupdate,  --no-rerere-autoupdate

After the rerere mechanism reuses a recorded resolution on the current conflict to update the files in the working tree, allow it to also update the index with the result of resolution​. --no-rerere-autoupdate is a good way to double-check what git-rerere(1) did and catch potential mismerges, before committing the result to the index with a separate git-add(1)​.

--ignore-space-change,  --ignore-whitespace,  --whitespace=<action>, -C<n>, -p<n>, --directory=<dir>, --exclude=<path>, --include=<path>, --reject

These flags are passed to the git-apply(1) program that applies the patch​.

Valid <action> for the --whitespace option are: nowarn, warn, fix, error, and error-all​.

--patch-format

By default the command will try to detect the patch format automatically​. This option allows the user to bypass the automatic detection and specify the patch format that the patch(es) should be interpreted as​. Valid formats are mbox, mboxrd, stgit, stgit-series, and hg​.

-i,  --interactive

Run interactively​.

--verify,  -n,  --no-verify

Run the pre-applypatch and applypatch-msg hooks​. This is the default​. Skip these hooks with -n or --no-verify​. See also githooks(5)​.

Note that post-applypatch cannot be skipped​.

--committer-date-is-author-date

By default the command records the date from the e-mail message as the commit author date, and uses the time of commit creation as the committer date​. This allows the user to lie about the committer date by using the same value as the author date​.

Warning
The history walking machinery assumes that commits have non-decreasing commit timestamps​. You should consider if you really need to use this option​. Then you should only use this option to override the committer date when applying commits on top of a base which commit is older (in terms of the commit date) than the oldest patch you are applying​.

--ignore-date

By default the command records the date from the e-mail message as the commit author date, and uses the time of commit creation as the committer date​. This allows the user to lie about the author date by using the same value as the committer date​.

--skip

Skip the current patch​. This is only meaningful when restarting an aborted patch​.

-S[<key-id>], --gpg-sign[=<key-id>], --no-gpg-sign

GPG-sign commits​. The <key-id> is optional and defaults to the committer identity; if specified, it must be stuck to the option without a space​. --no-gpg-sign is useful to countermand both commit​.gpgSign configuration variable, and earlier --gpg-sign​.

--continue,  -r,  --resolved

After a patch failure (e​.g​. attempting to apply conflicting patch), the user has applied it by hand and the index file stores the result of the application​. Make a commit using the authorship and commit log extracted from the e-mail message and the current index file, and continue​.

--resolvemsg=<msg>

When a patch failure occurs, <msg> will be printed to the screen before exiting​. This overrides the standard message informing you to use --continue or --skip to handle the failure​. This is solely for internal use between git-rebase(1) and git-am(1)​.

--abort

Restore the original branch and abort the patching operation​. Revert the contents of files involved in the am operation to their pre-am state​.

--quit

Abort the patching operation but keep HEAD and the index untouched​.

--retry

Try to apply the last conflicting patch again​. This is generally only useful for passing extra options to the retry attempt (e​.g​., --3way), since otherwise you’ll just see the same failure again​.

--show-current-patch[=(diff|raw)]

Show the message at which git-am(1) has stopped due to conflicts​. If raw is specified, show the raw contents of the e-mail message; if diff, show the diff portion only​. Defaults to raw​.

--allow-empty

After a patch failure on an input e-mail message lacking a patch, create an empty commit with the contents of the e-mail message as its log message​.

The commit author name is taken from the "From: " line of the message, and commit author date is taken from the "Date: " line of the message​. The "Subject: " line is used as the title of the commit, after stripping common prefix "[PATCH <anything>]"​. The "Subject: " line is supposed to concisely describe what the commit is about in one line of text​.

"From: ", "Date: ", and "Subject: " lines starting the body override the respective commit author name and title values taken from the headers​.

The commit message is formed by the title taken from the "Subject: ", a blank line and the body of the message up to where the patch begins​. Excess whitespace at the end of each line is automatically stripped​.

The patch is expected to be inline, directly following the message​. Any line that is of the form:

• three-dashes and end-of-line, or
• a line that begins with diff -, or
• a line that begins with `Index: `

is taken as the beginning of a patch, and the commit log message is terminated before the first occurrence of such a line​.

This means that the contents of the commit message can inadvertently interrupt the processing (see the Caveats section below)​.

When initially invoking git-am(1), you give it the names of the mailboxes to process​. Upon seeing the first patch that does not apply, it aborts in the middle​. You can recover from this in one of two ways:

1. skip the current patch by re-running the command with the --skip option​.
2. hand resolve the conflict in the working directory, and update the index file to bring it into a state that the patch should have produced​. Then run the command with the --continue option​.

The command refuses to process new mailboxes until the current operation is finished, so if you decide to start over from scratch, run git am --abort before running the command with mailbox names​.

Before any patches are applied, ORIG_HEAD is set to the tip of the current branch​. This is useful if you have problems with multiple commits, like running git-am(1) on the wrong branch or an error in the commits that is more easily fixed by changing the mailbox (e​.g​. errors in the From: lines)​.

The output from git-format-patch(1) can lead to a different commit message when applied with git-am(1)​. The patch that is applied may also be different from the one that was generated, or patch application may fail outright​. See the Discussion section above for the syntactic rules​.

Note that this is especially problematic for unindented diffs that occur in the commit message; the diff in the commit message might get applied along with the patch section, or the patch application machinery might trip up because the patch target doesn’t apply​. This could for example be caused by a diff in a Markdown code block​.

The solution for this is to indent the diff or other text that could cause problems​.

This loss of fidelity might be simple to notice if you are applying patches directly from a mailbox​. However, changes originating from Git could be applied in bulk, in which case this would be much harder to notice​. This could for example be a Linux distribution which uses patch files to apply changes on top of the commits from the upstream repositories​. This goes to show that this behavior does not only impact email workflows​.

Given these limitations, one might be tempted to use a general-purpose utility like patch(1) instead​. However, patch(1) will not only look for unindented diffs (like git-am(1)) but will try to apply indented diffs as well​.

This command can run applypatch-msg, pre-applypatch, and post-applypatch hooks​. See githooks(5) for more information​.

See the --verify/-n/--no-verify options​.

Everything below this line in this section is selectively included from the git-config(1) documentation​. The content is the same as what’s found there:

am​.keepcr

If true, git-am(1) will call git-mailsplit(1) for patches in mbox format with parameter --keep-cr​. In this case git-mailsplit(1) will not remove \r from lines ending with \r\n​. Can be overridden by giving --no-keep-cr from the command line​.

am​.threeWay

By default, git-am(1) will fail if the patch does not apply cleanly​. When set to true, this setting tells git-am(1) to fall back on 3-way merge if the patch records the identity of blobs it is supposed to apply to and we have those blobs available locally (equivalent to giving the --3way option from the command line)​. Defaults to false​.

am​.messageId

Add a Message-ID trailer based on the email header to the commit when using git-am(1) (see git-interpret-trailers(1))​. See also the --message-id and --no-message-id options​.

git-apply(1), git-format-patch(1)​.

Part of the git(1) suite