git-am

Apply and commit changes following a local patch file

$ git am [path/to/file.patch]

$ curl [[-L|--location]] [https://example.com/file.patch] | git apply

$ git am --abort

$ git am --reject [path/to/file.patch]

git am [] [ | ...]
git am [] < <patch-file>
git am --abort | --continue | --skip | --show-current-patch

--abort
    Stop the current patch application operation and revert to the state before git am began.

--continue
    Resume the patch application sequence after resolving conflicts or applying changes manually.

--skip
    Skip the current patch that failed to apply and proceed to the next one in the sequence.

--show-current-patch
    Display the patch currently being applied or that caused a conflict during the process.

--signoff / -s
    Add a Signed-off-by: line by the committer at the end of the commit message, indicating approval.

--keep-cr
    Preserve carriage returns (CR) at the end of lines when applying the patch, which can be useful for Windows-generated patches.

--3way
    Attempt a 3-way merge if a patch does not apply cleanly. This requires the original blob that the patch was created against to be available.

--reject
    When a patch does not apply cleanly, output a .rej file containing the rejected hunks instead of halting, and continue with subsequent patches.

-p<n>
    Remove n leading path components from the patch file names. For example, -p1 to strip the first directory level.

--whitespace=<option>
    Specify how to handle whitespace errors. Common options include nowarn, warn, fix, or error.

<Maildir>
    Path to a Maildir directory containing email messages, each potentially a patch to be applied.

<mbox>
    Path to an mbox file containing email messages, each potentially a patch to be applied.

Standard input (< <patch-file>)
    Apply a single patch read from standard input, typically redirected from a file containing the patch content.

git am is a powerful command used to apply a series of patches, typically received via email, onto a Git repository. It can consume patches from standard input, an mbox file, or a Maildir directory.
Unlike git apply, git am goes beyond just modifying files; it creates new commits for each patch, preserving author information, commit messages, and other metadata from the original email. This makes it ideal for integrating contributions from mailing lists, such as in open-source projects like the Linux kernel.
It intelligently parses common email headers (e.g., From, Subject, Date) to reconstruct accurate commit details. In case of conflicts, git am will pause, allowing for manual resolution, and provides options to continue, abort, or skip patches, ensuring a controlled application process for multi-patch series.

The working directory and index must be clean before starting git am, or it will typically error out, unless conflicts are pre-existing from a previous failed am operation.
Manual intervention is required to resolve merge conflicts; git am will pause until conflicts are resolved by the user.
While git am is robust, patches not generated by git format-patch (e.g., plain diffs from other tools, or improperly formatted email) might require additional options or manual adjustments for successful application.

A common workflow involves saving an email containing a patch (or multiple patches) into an mbox file or redirecting a single patch file to standard input. For instance, to apply patches from a file named patches.mbox, one would run git am patches.mbox.
If a patch fails to apply cleanly due to conflicts, git am will stop, allowing you to manually resolve the conflicts using git mergetool or direct file editing. After resolution, you stage the resolved files with git add and then run git am --continue to complete the commit and proceed with the next patch.
If a patch is deemed unapplicable or unwanted, git am --skip can be used to discard it and move on, or git am --abort to revert the entire operation, cleaning up any partially applied patches.

git am is specifically designed to understand various patch formats, primarily those generated by git format-patch, which include Git-specific metadata within the patch file itself. It intelligently parses email headers like From:, Subject:, Date:, Message-ID:, Commit:, Author:, and Date: to construct the commit message and set the correct author and committer information for the new commits.
This attention to detail ensures that the history created by git am accurately reflects the original contribution, even when processed through intermediate email systems, making it a reliable tool for maintaining historical integrity.

The git-am command has been a fundamental part of Git since its early development, reflecting its origins in the Linux kernel community's mailing list-centric workflow. It was designed to automate the process of applying email-borne patches, a common method of collaboration before distributed version control systems became widespread.
Its robustness in handling various email and patch formats, combined with its ability to reconstruct commit metadata, has made it an enduring and essential tool for integrating contributions from diverse sources in projects that rely on email-based patch submissions.

git-apply(1), git-format-patch(1), git-cherry-pick(1), git-rebase(1)