Table of Contents
introduction
In two previous posts, we discussed how to create a Git patch containing changes in a commit and email the Git patch to the recipient user, usually a developer on the same team or an open source mailing list.
In this article, we’ll discuss how an email patch recipient can apply patches they receive via 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 commits and merges them as commits into your local Git branch.
When you choose to collaborate on a software project via email, Git allows you to create and send revisions that represent a commit. These can be accessed as .mbox (mailbox) files and included in your local Git repository using the git am command.
git am vs git application – what is the difference between git am and git application?
The git am command is used to import commits from email patches in .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 app serve very similar functions – adding new commits to your local branch based on some previously made changes. The main difference is in the format of the content changes.
How to use git am?
Before using git am, you must have one or more patches represented as a .mbox (mbox) file:
- You or another developer use git format-patch to create one or more patches
- You or another user developer [git send-email](/blog/git send-email) to send these to you
- You must 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 you want to export to mbox. Then navigate to https://takeout.google.com/takeout, deselect all and then select “Gmail”, select “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 computer.
- Move the mbox file to the root directory of your project:
mv ~/Downloads/filename.mbox /path/to/git/repo - use
git am <filename.mbox>A command to create one or more commits on your current 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 the branch you are currently shipping with the contents of the patch files contained in the mbox file. The newly created commits are just normal commits – you can view with git log, see their changes with git diff HEAD^and so.
Error: git am failed, fix failed, fix not applied
In some cases, you may try and git am Repair and receive the error message “error: patch failed” and then another line that reads “error: patch not apply”:
$ git am filename.mbox
Applying: *Commit message...*
error: patch failed
error: patch does not apply
This can happen if your mbox patch changeset cannot be cleanly applied to the contents of your working directory. This is most likely due to content differences between the repo that created the mbox patch and the current state of your working directory.
If you’re running git status at this point, you’ll notice 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 conflicts with any files in your working directory, you can resolve those conflicts just like you do with a git merge. Once you’re done you can run git am –continue to apply the patch (along with conflict resolutions) and move on to the next patch.
If you realize you don’t need the patch in question, you can use git am –skip to ignore it and move on to the next patch.
If all else fails, you can always run git am –abort to abort your current git am session, store the changes in your working directory, and if that doesn’t work, make sure your repo is in sync with the patch creator before creating a new set of patches. Then restart Git am.
git am in progress
If you try to perform certain Git operations in the middle of a git am session, you may get an error like “git am is in progress”. Remember you can always use git am --abort To disable git am and continue using Git as usual.
What is the AM flag in Git?
Do not confuse them git amGit command we discuss 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 using git add.
God -a flag is a shortcut that allows you to add all changed files to the staging area at the same time you use it git commit. That is, it allows you to skip activation git add command.
God -m A flag allows specifying the commit message on the command line.
Use of these two flags at the same time can be specified as git commit -am "commit message..."And don’t confuse them with the git am command.
Summary
In this article, we explained what git am is, how git am differs from git app, how to use git am to import email revisions to your live branch, and we showed an 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 guide for developers, which dives into the Git code in an accessible way. We wrote it for developers who are curious to learn how Git works at the code level. To that end, we’ve documented the first version of Git’s code and discussed it in detail.
We hope you enjoyed this post! Feel free to email me at jacob@initialcommit.io with any questions or comments.
References
- Git SCM: git am docs – https://git-scm.com/docs/git-am
