git am: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git am replays a mailbox of patches, creating a commit for each - the counterpart to format-patch.

am applies emailed or generated patch series back into history as real commits, preserving authorship.

What it does

git am reads patches in mailbox format (from format-patch or an mbox) and applies each as a commit on the current branch, keeping the original author and message.

Common usage

Terminal

git am series.mbox
git am --3way series.mbox          # 3-way merge on conflict
git am < patch.eml
# after fixing a conflict:
git add <file> && git am --continue
git am --abort

Options

Flag	What it does
--3way / -3	Fall back to 3-way merge
--continue	Resume after resolving conflicts
--skip	Skip the current patch
--abort	Restore the pre-am state
-s / --signoff	Add a Signed-off-by line

Common errors in CI

error: "Patch failed at 0001 …" with "hint: Use git am --show-current-patch to see the failed patch" - the patch did not apply cleanly. Try --3way, resolve and --continue, --skip to drop it, or --abort to bail out.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git am: Usage, Options & Common CI Errors?