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

From Geos-chem
Jump to: navigation, search
(Resolving issues with patches)
(Adding a patch that was made to a previous version)
Line 68: Line 68:
 
== Adding a patch that was made to a previous version ==
 
== 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 v8-03-02 code. 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.
+
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. If you haven't done so already, [[Using_Git_with_GEOS-Chem#Code_directory|clone the current GEOS-Chem repository]]
+
1. '''Change''' into your local GEOS-Chem code directory.
  
:2. Start the Git GUI interface:
+
cd /path/to/my/GEOS-Chem/Code
  
    git gui &
+
2. '''Start Gitk''' and [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''view the revision history''']].
  
:3. Start the Gitk browser. From the dropdown menu in Git Gui, select:
+
gitk --all &
  
    Repository / Visualize All Branch History
+
3. 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.
  
:4. In the Gitk revision, look for the parent commit of the patch in the revision history (upper-left) 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.
+
4. [[Branching#Use_Gitk_to_create_a_new_branch|'''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.
  
:5. We will create a new branch from the parent commit into which the code updates will be placed. Once you have found the parent commit, right click on the commit text to open a context menu. Select:
+
5. [[Branching#Check_out_a_branch_with_GitK|'''Checkout the new branch''']] that you just created.
  
    Create new branch  (name it '''patch-install-point''' and hit '''OK''')
+
6. Let's assume that your patch file is located at: <tt>~/my_patch_directory/patch_file.diff</tt>.  [[#Validate the validity of this patch.
  
:6. We need to [[#Switching between branches|checkout]] (i.e. switch to) the new branch. Go back to the Git GUI.  From the dropdown menu, select:
 
  
    Branch / Checkout (and then click on '''patch-install-point''')
+
'''Apply this patch''' by typing:
  
:7. Locate the patch file that contains the update you wish to add to the code. Let's assume that this is called <tt>patch-file.diff</tt>.  We will now apply this to your source code directory:
+
git am < ~/my_patch_directory/patch-file.diff
  
      git am < ~/my_patch_directory/patch-file.diff
+
or where
  
 
:NOTE: <tt>patch-file.diff</tt> does not have to be in the source code directory. It can be anywhere, as long as you specify the full file path. Here we assume it’s in <tt>~/my_patch_directory</tt>.)
 
:NOTE: <tt>patch-file.diff</tt> does not have to be in the source code directory. It can be anywhere, as long as you specify the full file path. Here we assume it’s in <tt>~/my_patch_directory</tt>.)
Line 129: Line 128:
  
 
--[[User:Bmy|Bob Y.]] 09:58, 17 August 2011 (EDT)
 
--[[User:Bmy|Bob Y.]] 09:58, 17 August 2011 (EDT)
 
  
 
== Resolving issues with patches ==
 
== Resolving issues with patches ==

Revision as of 15:44, 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)

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 and view the revision history.

gitk --all &

3. 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.

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

5. Checkout the new branch that you just created.

6. Let's assume that your patch file is located at: ~/my_patch_directory/patch_file.diff. [[#Validate the validity of this patch.


Apply this patch by typing:

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

or where

NOTE: patch-file.diff does not have to be in the source code directory. It can be anywhere, as long as you specify the full file path. Here we assume it’s in ~/my_patch_directory.)
8. In the Git GUI, press the F5 key to refresh the display.
9. In the GitK browser, press the F5 key to refresh the display.
10. Now we want to merge the master branch into the patch-install-point branch. This will bring in all of the previous commits from the master branch into the patch-install-point branch, while keeping the new commits from the patch at the top of the revision history. Switch to the Git Gui window and pick from the menu:
     Merge / Local Merge (and then click on master)
11. The merge may result in some conflicts in some source code files. A conflict is a difference in the source code which Git cannot rectify. Most often conflicts are caused by 2 comments having the same number. Git will add the following lines to the source code:
   <<<<<HEAD
   ... lines of existing code ...
   =====
   ... lines of new code ...
   >>>>>
If there are conflicts, you will have to go through these manually. You can just hand-edit the source code files with your favorite text editor. If there are no conflicts, you can skip ahead to Step 14.
12. Once you have finished resolving all conflicts, commit the modified files to the repository. In the Git Gui, click on each of the files in the “Unstaged Changes” window (this will tell Git to commit them to the repository). Then click on the “Sign off” button and click on the “Commit” button.
13. At this point you will have 2 branches. The master branch represents the pristine, unmodified code from the remote repository. The patch-install-point branch represents master branch plus the code from the patch that we added.
14. Test the code in patch-install-point to make sure that it is functioning properly (i.e. run a benchmark simulation or a short test run).
15. Once you are certain that the code in patch-install-point is good, then merge patch-install point back into the master branch. From the Git GUI dropdown menu:
  Branch / Checkout    and then click on master                # Switches to the master branch

  Merge / Local Merge  and then click on patch-install-point   # Merges patch-install-point into master

  Branch / Delete      and then click on patch-install-point   # Deletes patch-install-point branch    

--Bob Y. 09:58, 17 August 2011 (EDT)

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 --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