Using patches to share your updates with others

Previous | Next | Guide to using Git with GEOS-Chem

1. Introduction to Git
2. Installing Git
3. First-time Git setup
4. Cloning (i.e. downloading for the first time)
5. Ignoring files
6. Viewing the revision history
7. Using Git GUI
8. Branching
9. Committing
10. Tagging
11. Merging
12. Receiving updates (aka pulling)
13. Using patches to share your updates with others
14. Advanced Git usage
15. Git and Github tutorials

Overview

One of the really nice features of Git is that it can create patch files, or files which contain a list of changes that can be imported into someone else's local Git repository. Using patch files totally obviates the need of having to merge differences between codes manually.

The other way to share your code updates with others is to create a pull request from your local Github account. This will be described later.

Creating a patch file to share with others

To create a patch file containing the code differences between a branch of your code with your master branch, or since type the following text:

git format-patch master..BRANCH_NAME --stdout > my-patch-file.diff

where BRANCH_NAME is the name of the branch that you want to compare against the master branch.

You can also create a patch file for a given number of past commits. Typing:

git format-patch -3 --stdout > my-patch-file.diff

will create a patch file for the last 3 commits on the currently checked-out branch. If you want the most recent commit then use -1 instead, etc.

These commands will pipe the output from the git format-patch command to a file named by you (in this case my-patch-file.diff, but you may select whatever name you wish). You can then include the patch file as an email attachment and send it to other GEOS-Chem users, or the GEOS-Chem Support Team.

When sending patch files to others, it is important that you specify the parent commit (i.e. the commit that immediately precedes where the patch was made) for your patch file.

--Bob Yantosca (talk) 15:27, 21 June 2019 (UTC)

Checking the validity of a patch file

Other users can also send you their source code revisions as patch files. If you want to check the status of a Git patch file (i.e. what it will actually do) before you apply it to your repository, you can use the git apply command as follows:

% git apply --stat my-patch-file.diff

 GeosCore/aerosol_mod.F |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

The sample output listed above indicates that the patch contained 4 insertions and 3 deletions from only one file (aerosol_mod.F).

Note that the git apply --stat command does not apply the patch, but only shows you the stats about what it'll do. For more detailed information about the patch, you can open it in a text editor and examine it manually.

You can also find out if the patch will install in your Git repository, or if there will be problems. You can also use the git apply command to do this:

git apply --check my-patch-file.diff

The most often error that is encountered is that the patch was made from an earlier version of GEOS-Chem. In that instance the situation can usually be rectified by having the sender of the patch do a git pull to the last-released GEOS-Chem version and then to create the patch again.

--Bob Yantosca (talk) 15:27, 21 June 2019 (UTC)

Reading a patch file into your local source code folder

To ingest a patch file into your local Git repository, follow these steps:

(1) Create a new branch into which you will load the patch.

(2) Check out the branch you just created. (If you used Git GUI to create the branch, this will be done for you automatically).

(3) Check the validity of the patch, as described above.

(4) Apply the patch. Type:

git am < their-patch-file.diff

This will load the commits contained in the patch to the branch that you have checked out.

--Bob Yantosca (talk) 15:28, 21 June 2019 (UTC)

Adding a patch that was made to a previous version

Let's say you are currently working on the latest version of GEOS-Chem, and somebody gives you a patch that they added into their own GEOS-Chem code, which is based on an older version. You can add the patch into your code in such a way that the modification will be at the head of the revision history. Here is the procedure.

(1) Change into your local GEOS-Chem code directory.

cd /path/to/my/GEOS-Chem/Code

(2) Start Gitk.

gitk --all &

(3) View the revision history with Gitk.

(4) Find the parent commit of the patch that you were given in the Gitk revision history window. The parent commit is the one immediately preceding the patch. If you are not sure where the parent commit is, you can ask the person who sent you the patch.

(5) Create a new branch with GitK at the parent commit of the patch. In this example we'll call it feature/NewFeature, but you can name it something else.

(6) Checkout the new branch that you just created.

(7) Locate the patch file. For this example, we'll assume that your patch file is located at: ~/my_patch_directory/patch_file.diff. The patch file can be applied from anywhere, as long as you supply the full file path.

(8) Check the validity of this patch as described above.

(9) Apply the patch by typing:

git am < ~/my_patch_directory/patch-file.diff

(10) View the revision history again. You should see the commits from the patch file contained in the branch feature/NewFeature (or whatever you named the branch).

(11) Merge the master branch up to the feature/NewFeature branch]]. This will bring all of the commits from master (which is newer) into feature/NewFeature.

(12) Resolve any conflicts caused by the merge.

At this point you will have 2 branches. The master branch represents the pristine, unmodified code from the remote repository. The feature/NewFeature branch represents master branch plus the code from the patch that we added.

--Bob Yantosca (talk) 15:59, 21 June 2019 (UTC)

Resolving issues with patches

Here are some common issues that you might encounter when using patches, and how to resolve them.

Invalid email address error

If you get the the following error while trying to run the command git am < their-patch-file.diff:

     Patch does not have a valid e-mail address.

Then use this command instead:

     git apply their-patch-file.diff

which should ingest the changes from the patch file into your repository. Why the difference? Long story short:

• If their-patch-file.diff was created with the git format-patch command, then it will contain the name of the committer plus the commit log message at the top of the file. The git am command uses this information to create the commit message in your repository.
• If on the other hand, their-patch-file.diff was created in gitk by right-clicking on the Make patch menu entry, then it will lack the email address of the committer and log message. This will confuse the git am command. Using git apply will ingest the changes into your repository, but you will have to add the commit message yourself in the git gui.

--Bob Y. 13:35, 2 October 2013 (EDT)

"Patch does not apply" error

If you get error output similar to this while trying to run the command git am < their-patch-file.diff:

error: patch failed: file.c:137
error: file.c: patch does not apply
error: patch failed: Makefile:24
error: libavfilter/Makefile: patch does not apply
Patch failed at 0001 PATCH DESCRIPTION
When you have resolved this problem run "git am --resolved".
If you would prefer to skip this patch, instead run "git am --skip".
To restore the original branch and stop patching run "git am --abort

Then do:

1. git apply --reject --whitespace=fix their-patch-file.diff
2. Inspect conflicts in .rej files and manually resolve them
3. Commit your changes

--Melissa Sulprizio (talk) 17:25, 19 June 2019 (UTC)

Further reading

1. Patching (Pro Git book)
2. How to create and apply a patch with Git (Ariejan.net)
3. Creating and applying patch files in Git (Mjingo)

---

Previous | Next | Guide to using Git with GEOS-Chem