Image of git am | Apply an email patch in Git

ADVERTISEMENT

Table of Contents

Introduction

In two previous posts, we've discussed how to create a Git patch containing a commit's changes and email a Git patch to a recipient user, usually a developer on the same team or an open-source mailing list.

In this article, we'll discuss how the email patch recipient can apply patches that they receive through email to their local Git repository as a new commit.

What is git am command?

The git am command takes one or more Git email patches and incorporate them as commits on your local Git branch.

When you choose to collaborate on a software project over email, Git enables you to generate and send patches that represent commits. These can be accessed as .mbox (mailbox) files and included in your local Git repository using the git am command.

git am vs git apply - What is the difference between git am and git apply?

The git am command is used to import commits from email patches in the .mbox format, while git apply is used to directly apply the output of the git diff command as a new commit.

So git am and git apply serve very similar functions - adding new commits to your local branch based on some previously generated changes. The main difference is the format of the content changes.

How to use git am?

Before using git am, you need to have one or more patches represented as a .mbox (mbox) file:

  1. You or another dev uses git format-patch to create one or more patches
  2. You or another dev uses [git send-email](/blog/git send-email) to send these to you
  3. You need to export this email in mbox format. Most email clients allow exporting in mbox format. In Gmail you can add a new custom label to the emails that you want to export to mbox. Then browse to https://takeout.google.com/takeout, deselect all and then choose "Gmail", choose "All Mail data included", deselect all and scroll down and select your custom label, scroll down and click "Next" followed by "Create export". Download the mbox file to your local machine.
  4. Move the mbox file to your project root directory: mv ~/Downloads/filename.mbox /path/to/git/repo
  5. Use the git am <filename.mbox> command to create a one or more commits on your currently active branch, based on the contents of the mbox patch files.

git am example

As mentioned in the previous section, you can run git am with the name of the mbox file to import as follows:

$ git am filename.mbox
Applying: *Commit message...*

This will actually create one or more commits on your currently checked out branch with the content of the patch files included in the mbox file. These newly created commits are just ordinary commits - you can view with git log, see their changes with git diff HEAD^, etc.

error: git am failed, patch failed, patch does not apply

In some cases, you might try and git am a patch and get the error message "error: patch failed" and then another line that reads "error: patch does not apply":

$ git am filename.mbox
Applying: *Commit message...*
error: patch failed
error: patch does not apply

This can happen if the changeset in your mbox patch isn't able to be cleanly applied into the content of your working directory. This is likely due to content differences between the repo that generated the mbox patch and the current state of your working directory.

If you run git status at this time, you'll notice some additional information in your status message:

$ git status
You are in the middle of an am session.
  (fix conflicts and then run "git am --continue")
  (use "git am --skip" to skip this patch)
  (use "git am --abort" to restore the original branch)

If the patch you tried to apply is in conflict with any files in your working directory, you can resolve those conflicts just like you do in a git merge. Once done you can run git am --continue to apply the patch (along with conflict resolutions) and move on to the next one.

If you realize you don't need the patch in question, you can use git am --skip to ignore it and move onto the next one.

If all else fails, you can always run git am --abort to abort your current git am session, stash the changes in your working directory and if that doesn't work, ensure that your repo is in sync with the patch creator's before generating a new set of patches. Then run git am again.

git am is in progress

If you try to perform certain Git actions while in the middle of a git am session, you might get an error like "git am is in progress". Remember you can always use git am --abort to abort the git am session and continue using Git as normal.

What is AM flag in Git?

Don't get confused between git am, the Git command we're discussing in this post, and the git commit -am flags. The git commit command is used to create a new commit from the changes manually added to the staging area via git add.

The -a flag is a shortcut that allows you to add all modified files to the staging area at the same time as you use git commit. I.e. it allows you to skip running the git add command.

The -m flag allows specifying the commit message on the command-line.

Using both of these flags at once can be specified as git commit -am "commit message...", and shouldn't be confused with the command git am.

Summary

In this article, we explained what git am is, how git am differs from git apply, how to use git am to import email patches onto your active branch, and showed some example usage of git am.

Next steps

If you're interested in learning more about how Git works under the hood, check out our Baby Git Guidebook for Developers, which dives into Git's code in an accessible way. We wrote it for curious developers to learn how Git works at the code level. To do this, we documented the first version of Git's code and discuss it in detail.

We hope you enjoyed this post! Feel free to shoot me an email at jacob@initialcommit.io with any questions or comments.

References

  1. Git SCM: git am docs - https://git-scm.com/docs/git-am

Final Notes