Difference between revisions of "Using patches to share your updates with others"

From Geos-chem
Jump to: navigation, search
(Reading a patch file into your local repository)
(Reading a patch file into your local repository)
Line 48: Line 48:
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:27, 21 June 2019 (UTC)
 
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:27, 21 June 2019 (UTC)
  
== Reading a patch file into your local repository ==
+
== Reading a patch file into your local source code folder ==
  
 
To ingest a patch file into your local Git repository, follow these steps:
 
To ingest a patch file into your local Git repository, follow these steps:
Line 63: Line 63:
  
 
This will load the commits contained in the patch to the branch that you have checked out.
 
This will load the commits contained in the patch to the branch that you have checked out.
 +
 +
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:28, 21 June 2019 (UTC)
  
 
== Resolving issues with patches ==
 
== Resolving issues with patches ==

Revision as of 15:28, 21 June 2019

Previous | Next | Guide to using Git with GEOS-Chem | Getting Started with GEOS-Chem | GEOS-Chem Main Page

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)

Resolving issues with patches

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 --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. How to create and apply a patch with Git

Previous | Next | Guide to using Git with GEOS-Chem | Getting Started with GEOS-Chem | GEOS-Chem Main Page