Command Reference

git-am Tutorial

Apply mailbox patch series as real commits, preserving author/message metadata in patch-by-email workflows.

Who This Is For
  • Developers who already know basic commit and branch actions
  • Readers who want to understand command boundaries and risk
Prerequisites
  • A basic mental model of worktree, index, and commits
  • Comfort reading `git status` and a small commit graph
Common Risks
  • Using local cleanup commands on already shared history
  • Continuing to rewrite before confirming a recovery path

The short version

git am applies email-style patches and records them as commits, not just working-tree edits.

Best-fit scenarios

  • ingesting mailing-list patch series
  • preserving original author/subject metadata
  • importing changes in non-platform collaboration models

Core flow

git am 0001-fix.patch
# or
git am *.patch

If conflicts happen:

git am --continue
git am --skip
git am --abort

Why it differs from git apply

  • git apply: apply file diffs only
  • git am: apply diffs and create commits with mail metadata

Safer usage pattern

  1. run on a temporary branch first
  2. verify base alignment before apply
  3. avoid repeated blind --skip; keep recovery checkpoints
Base mismatch is the main `am` failure cause

Patch-series context drift can produce cascading conflicts. Syncing base first is often the cheapest prevention step.

Common mistakes

Mistake 1: expecting every patch to apply automatically

Context divergence still requires human conflict resolution.

Mistake 2: aborting immediately and losing useful progress

git am applies mailbox-format patches onto the current branch and creates new commits, preserving the original author information and commit metadata. Think of it as the step where "patches formally enter local history from an external source."

Evaluate already-applied commits before discarding series state.

Mistake 3: skipping patches without traceability

  • Apply a series of patches received from external contributors or mailing lists directly onto your local branch.
  • In a patch-based workflow, use git am to convert received .patch files into proper commit records.
  • When you need to preserve the committer identity and full commit message, use git am rather than manually copying changes.

Later it becomes hard to explain sequence gaps.

Patch application surfacePatch application commands formally incorporate external patches into local branches. The key distinction is whether they create commits and whether they preserve email headers.
Input
Mailbox-format patch filesCurrent branch
Output
New commits (preserving author info)Advanced branch pointer
am and apply have clear division: am creates commits, apply only changes the working tree.

Special cases and boundaries

  • When patch application fails, git am --abort rolls back to the pre-application state without leaving half-finished commits.
  • Before running git am, confirm a clean working tree with git status and preview the current patch with --show-current-patch.
  • If a patch's context does not match the current codebase, application will fail — first verify which version the patch was generated against.
  • Email encoding, signature lines, and whitespace formatting can all affect patch parsing; use --ignore-whitespace or --3way for more tolerance when needed.

Good follow-up reads

  1. git-format-patch
  2. git-send-email
  3. recover after wrong cherry-pick

Related Reads

CommandsCore
git init Tutorial
CommandsCore
git clone Tutorial
CommandsCore
git status Tutorial

Previous / Next

Previousgit-rev-parse TutorialCommandsNextgit-apply TutorialCommands