Git Mailbox Patch Series: Apply with git am

Advanced

The mailbox workflow: format-patch → am

`git format-patch` turns selected commits into mailbox-style messages. `git am` consumes those messages and reconstructs commits on the current branch. The resulting commits use the patch message for authorship and commit-message information; the person running `git am` becomes the committer.

git format-patch -o patches BASE..HEAD
git am patches/*.patch
git log --format="%h | author=%an <%ae> | committer=%cn <%ce> | %s" -n 2

?

Apply patch files or a mailbox stream

The initial `git am` invocation accepts one or more mailbox files. A directory is treated as a Maildir. If you omit the mailbox argument, Git reads the mailbox from standard input, which is useful when a mailbox is being piped or redirected.

git am patches/0001-first-change.patch patches/0002-second-change.patch
git am < series.mbox

A series is processed in order. If a patch applies cleanly, Git creates its commit and continues with the next message. Because `git am` operates on the current branch, start it from the branch where the reconstructed commits belong.

?

Authorship, commit messages, and sign-off

The `From:` line supplies the commit author identity and the `Date:` line supplies the author date. The `Subject:` line supplies the commit title after Git removes a common `[PATCH ...]` prefix. The mailbox body contributes the remainder of the commit message. The committer identity is the identity of the person running `git am`.

git am --signoff patches/*.patch
git log -1 --format="%an <%ae> | %cn <%ce> | %B"

`--signoff` adds a `Signed-off-by` trailer using the current committer identity. This changes the resulting commit message; it does not change who the patch says its author is.

?

When a patch does not apply

If a patch cannot be applied cleanly, `git am` stops in the middle of the series. The repository enters an `am` operation state. Do not start another mailbox while that state is active; first resolve, skip, retry, quit, or abort the current operation.

git am patches/*.patch
git status
git am --show-current-patch=diff
git am --show-current-patch=raw

`--show-current-patch=diff` shows the diff portion of the patch currently being processed. `--show-current-patch=raw` shows the raw message. These are inspection tools for understanding the stopped operation before choosing a recovery path.

?

Resolve the patch and continue the series

For a real conflict, resolve the files in the working tree and update the index so it represents the result you want committed. Then run `git am --continue`. Git uses the authorship and commit message already extracted from the mailbox and creates the commit from the resolved index.

git status
# resolve the conflicted files
git add path/to/resolved-file
git am --continue

The important boundary is that `git am --continue` completes the current mailbox patch; it is not the same operation as `git commit` followed by manually copying metadata. Git keeps the patch-series state and continues with later messages.

Skip a patch or abort the entire operation

Use `git am --skip` when the current patch should be omitted and the series should continue with the next mailbox message. Use `git am --abort` when you want to abandon the operation and restore the branch and affected files to their pre-`am` state.

git am --skip
git am --abort

?

Use three-way fallback when direct application fails

`--3way` tells `git am` to fall back to a three-way merge when the patch does not apply cleanly, provided the patch records the required blob identity and the relevant blob is available locally. A three-way attempt can still produce a conflict; if it does, resolve the conflict and use `git am --continue`.

git am --3way series.mbox
# if Git stops with a conflict:
git add path/to/resolved-file
git am --continue

This is a different recovery mechanism from simply forcing a textual patch through. The three-way path uses Git object information recorded by the patch when the required objects are available.

Mailbox cleanup with scissors

Mail messages can contain discussion before the actual patch. With `--scissors`, Git removes body content before a scissors line and then processes the patch portion. This is useful when a patch is embedded in a reply or discussion that follows the mailbox conventions described by the Git documentation.

git am --scissors discussion-with-patch.mbox

Use this only when the mailbox actually uses the scissors marker. It is a message-parsing control, not a patch conflict resolver.

Patch application, hooks, and verification boundaries

By default, `git am` runs the `applypatch-msg` and `pre-applypatch` hooks; `--no-verify` skips those hooks. The `post-applypatch` hook cannot be skipped. This lesson does not teach hook authoring itself; the point here is to understand that applying a mailbox can invoke repository policy hooks.

git am --no-verify series.mbox

Do not treat `--no-verify` as a generic way to make a broken patch apply. It bypasses the two skippable hooks; it does not remove patch applicability requirements.

What `git am` does—and does not—own

`git format-patch` prepares the mailbox messages; `git am` consumes them and creates commits. `git apply` consumes raw diff text without creating commits. `git send-email` is the separate email-transport surface. `git diff` produces comparisons and may be used to create raw patch text, but it is not the mailbox-to-commit operation. `git bundle` transports Git objects and refs rather than textual email patches.

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official source boundary

Git command semantics in this lesson are based only on the official Git documentation for `git-am` and its explicitly referenced patch workflow surfaces. No third-party documentation is used for Git command semantics.