Difference between revisions of "Receiving updates (aka pulling)"

From Geos-chem
Jump to: navigation, search
(Get all updated branches and tags from the GEOS-Chem remote repository)
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''''[[Merging|Previous]] | [[Sharing updates with patches|Next]] | [[Guide to using Git with GEOS-Chem]] | [[Getting Started with GEOS-Chem]] | [[Main Page|GEOS-Chem Main Page]]'''''
+
'''''[[Merging|Previous]] | [[Using patches to share your updates with others|Next]] | [[Guide to using Git with GEOS-Chem]]'''''
 +
 
 +
#[[Introduction to Git]]
 +
#[[Installing Git]]
 +
#[[First-time Git setup]]
 +
#[[Cloning (i.e. downloading for the first time)]]
 +
#[[Ignoring files]]
 +
#[[Viewing the revision history]]
 +
#[[Using Git GUI]]
 +
#[[Branching]]
 +
#[[Committing]]
 +
#[[Tagging]]
 +
#[[Merging]]
 +
#<span style="color:blue">'''Receiving updates (aka pulling)'''</span>
 +
#[[Using patches to share your updates with others]]
 +
#[[Advanced Git usage]]
 +
#[[Git and Github tutorials]]
 +
 
  
 
== Overview ==
 
== Overview ==
Line 7: Line 24:
 
== Getting updates from the GEOS-Chem repository on Github ==
 
== Getting updates from the GEOS-Chem repository on Github ==
  
When a new GEOS-Chem version is released, we recommend that you [[#Downloading a new GEOS-Chem version|download it into a new local directory]] with the '''git clone''' command.
+
When a new GEOS-Chem version is released, we recommend that you [[#Downloading a new GEOS-Chem version|download it from our GEOS-Chem Github repository]] into a new source code folder in your disk space.
  
However, there may be times when "patches" (i.e. minor updates to fix bugs or other issues) need to be applied to an existing GEOS-Chem version.  The easiest way to obtain patches is to use the '''git pull''' command, as follows:
+
However, there may be times when patches and/or minor GEOS-Chem versions are released.  These are typically done in order to fix issues in an prior GEOS-Chem version.  If you already have an existing GEOS-Chem source code directory, you can receive these updates into your source code folder by using the '''git pull'' command, as described below.
  
 
=== Get all updated branches and tags from the GEOS-Chem remote repository ===
 
=== Get all updated branches and tags from the GEOS-Chem remote repository ===
  
1. Change to your local copy of the GEOS-Chem code directory, e.g.
+
(1) '''Change''' into your local GEOS-Chem code directory.
  
 
  cd /path/to/my/GEOS-Chem/Code
 
  cd /path/to/my/GEOS-Chem/Code
  
2. [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']].  Your plot will look something like this.
+
(2) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history with Gitk''']].  You will see something similar to this:
  
 
[[Image:GitPullStep1.png]]
 
[[Image:GitPullStep1.png]]
Line 23: Line 40:
 
In this example, the '''master''' branch is checked out, which corresponds to GEOS-Chem version 12.3.2.
 
In this example, the '''master''' branch is checked out, which corresponds to GEOS-Chem version 12.3.2.
  
3. Let's say that you need to add a new feature off of one of the development branches.  '''Pull all remote branch references''' into your local directory by typing:
+
(3) Let's say that you need to add a new feature off of a development branch (say, '''dev/12.4.0''').  '''Pull all remote branch references''' into your local directory by typing:
  
 
  git pull
 
  git pull
  
4. [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  You should now see something like this:
+
(4) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  You should now see something like this:
  
 
[[Image:GitPullStep2.png]]
 
[[Image:GitPullStep2.png]]
Line 33: Line 50:
 
Note that several pointers to remote branches (beginning with '''remotes/origin''') have been added to your repository.  These remote branch references "point" to branches that are present at the GEOS-Chem remote repository on Github.  However, you cannot use any of these branches in your local code directory until you create local branches for them.
 
Note that several pointers to remote branches (beginning with '''remotes/origin''') have been added to your repository.  These remote branch references "point" to branches that are present at the GEOS-Chem remote repository on Github.  However, you cannot use any of these branches in your local code directory until you create local branches for them.
  
5. Let's say that you need to work off the '''dev/12.4.0''' branch.  [[Branching#Switching_between_.28aka_.22checking_out.22.29_branches|'''Create a local branch''']] for dev/12.4.0 in your code directory.  Type:
+
(5) [[Branching#Switching_between_.28aka_.22checking_out.22.29_branches|'''Create a local branch''']] for '''dev/12.4.0''' in your code directory.  Type:
  
 
  git checkout dev/12.4.0
 
  git checkout dev/12.4.0
  
You will see this text printed at the command line:
+
You will see output similar to this:
  
 
  git checkout dev/12.4.0
 
  git checkout dev/12.4.0
Line 44: Line 61:
 
  Switched to a new branch 'dev/12.4.0'
 
  Switched to a new branch 'dev/12.4.0'
  
6. [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  Now you will see that you have a '''dev/12.4.0''' local branch&mdash;which is current with the state of the code at the remote repository&mdash;checked out.
+
(6) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  Now you will see that you have a '''dev/12.4.0''' local branch&mdash;which is current with the state of the code at the remote repository&mdash;checked out.
  
 
[[Image:GitPullStep3.png]]
 
[[Image:GitPullStep3.png]]
  
7. [[Branching#Creating_branches|'''Create a new branch''']] off of '''dev/12.4.0''' and start adding your code updates there.
+
(7) [[Branching#Creating_branches|'''Create a new branch''']] off of '''dev/12.4.0''' and start adding your code updates there.
 +
 
 +
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:36, 21 June 2019 (UTC)
  
 
=== Getting updates from the GEOS-Chem repository in to a particular branch ===
 
=== Getting updates from the GEOS-Chem repository in to a particular branch ===
  
In the previous example, we pulled all of the  
+
In the previous example, we demonstrated how to pull all remote branch references into your local source code folder.  However, this is often not necessary.  Very often you will just want to pull updates into a single branch, as demonstrated below.
 +
 
 +
(1) '''Change''' into your local GEOS-Chem code directory.
 +
 
 +
cd /path/to/my/GEOS-Chem/Code
 +
 
 +
(2) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history with Gitk''']].  You will see something similar to this:
 +
 
 +
[[Image:GitPullStep1.png]]
 +
 
 +
(3) [[Branching#Creating_branches|'''Create a new branch''']] off of '''master''' (let's call it '''feature/MyFeature''').
 +
 
 +
(4) [[Branching#Switching_between_.28aka_.22checking_out.22.29_branches|'''Check out''']] the '''feature/MyFeature''' branch (or whatever you named it).
 +
 
 +
(5) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  You should see something similar to this:
 +
 
 +
[[Image:GitPullStep4.png]]
 +
 
 +
(6) '''Pull a branch from the remote GEOS_Chem repository into the '''feature/MyFeature''' branch:
 +
 
 +
git pull origin dev/12.4.0
 +
 
 +
You will see text similar to this:
 +
 
 +
From github.com:geoschem/geos-chem
 +
  * branch              dev/12.4.0 -> FETCH_HEAD
 +
Updating 8577e970..93e8ad81
 +
Checking out files: 100% (173/173), done.
 +
Fast-forward
 +
  GeosCore/Makefile                          |  14 +-
 +
  GeosCore/RnPbBe_mod.F                      |  33 +-
 +
  ...etc. -- this is the list of files that are being modified ...
 +
173 files changed, 12105 insertions(+), 17449 deletions(-)
 +
 +
Here, '''git pull origin''' means to pull the updates from the same repository that your GEOS-Chem source code folder was cloned from.  This will almost always be the GEOS-Chem Github repository.
 +
 
 +
(7) [[Viewing_the_revision_history#Use_Gitk_to_see_a_graphical_display|'''View the revision history''']] again.  You will see that the '''feature/MyFeature''' branch is now at the same commit as the '''dev/12.4.0''' branch.
 +
 
 +
[[Image:GitPullStep5.png]]
 +
 
 +
(8) At this point you can make further code edits into the '''feature/MyFeature''' branch.
 +
 
 +
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:35, 21 June 2019 (UTC)
 +
 
 +
== Getting updates from a directory other than the remote GEOS-Chem Github repository ==
 +
 
 +
In some cases, you might need to pull updates from another user's GEOS-Chem source code directory.  To do this, [[#Getting updates from the GEOS-Chem repository in to a particular branch|follow Steps 1-4 in the previous section]].
 +
 
 +
Then type:
  
 +
git pull /path/to/other/Git/repository BRANCH-NAME
  
2. '''Create a new branch
+
This will copy the updates from BRANCH-NAME in the other user's repository into your currently checked-out branch.
  
 +
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:08, 21 June 2019 (UTC)
  
# [[#Creating branches|Make a new branch]] named '''patch''' (or something similar).
+
== Further reading ==
# [[#Creating branches|Check out]] the '''patch''' branch.  Now we are ready to obtain the updates from the remote server.
+
# Use the '''git pull''' command to download the updated files. Type:
+
      git pull origin master
+
# Try compiling GEOS-Chem and running for few time steps to make sure everything is fine.
+
# [[#Creating branches|Check out]] the '''master''' branch.
+
# [[#Merging|Merge]] the '''patch''' branch into your '''master''' branch.
+
# [[#Deleting branches|Delete]] the '''patch''' branch.
+
  
This will merge the changes from the '''master''' branch of the remote repository into your '''master''' branch.
+
#[https://git-scm.com/docs/git-pull ''Git pull'' (Git documentation)]
 +
#[https://www.atlassian.com/git/tutorials/syncing/git-pull ''Git pull'' (Atlassian Git tutorial)]
 +
#[https://guide.freecodecamp.org/git/git-pull/ ''Git pull'' (FreeCodeCamp)]
  
  
 
----
 
----
'''''[[Merging|Previous]] | [[Sharing updates with patches|Next]] | [[Guide to using Git with GEOS-Chem]] | [[Getting Started with GEOS-Chem]] | [[Main Page|GEOS-Chem Main Page]]'''''
+
'''''[[Merging|Previous]] | [[Using patches to share your updates with others|Next]] | [[Guide to using Git with GEOS-Chem]]'''''

Latest revision as of 20:29, 5 August 2019

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

On this page, we provide information about how you can get "pull" updates from the GEOS-Chem repository, or any other Git repository.

Getting updates from the GEOS-Chem repository on Github

When a new GEOS-Chem version is released, we recommend that you download it from our GEOS-Chem Github repository into a new source code folder in your disk space.

However, there may be times when patches and/or minor GEOS-Chem versions are released. These are typically done in order to fix issues in an prior GEOS-Chem version. If you already have an existing GEOS-Chem source code directory, you can receive these updates into your source code folder by using the 'git pull command, as described below.

Get all updated branches and tags from the GEOS-Chem remote repository

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

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

(2) View the revision history with Gitk. You will see something similar to this:

GitPullStep1.png

In this example, the master branch is checked out, which corresponds to GEOS-Chem version 12.3.2.

(3) Let's say that you need to add a new feature off of a development branch (say, dev/12.4.0). Pull all remote branch references into your local directory by typing:

git pull

(4) View the revision history again. You should now see something like this:

GitPullStep2.png

Note that several pointers to remote branches (beginning with remotes/origin) have been added to your repository. These remote branch references "point" to branches that are present at the GEOS-Chem remote repository on Github. However, you cannot use any of these branches in your local code directory until you create local branches for them.

(5) Create a local branch for dev/12.4.0 in your code directory. Type:

git checkout dev/12.4.0

You will see output similar to this:

git checkout dev/12.4.0
Checking out files: 100% (173/173), done.
Branch 'dev/12.4.0' set up to track remote branch 'dev/12.4.0' from 'origin'.
Switched to a new branch 'dev/12.4.0'

(6) View the revision history again. Now you will see that you have a dev/12.4.0 local branch—which is current with the state of the code at the remote repository—checked out.

GitPullStep3.png

(7) Create a new branch off of dev/12.4.0 and start adding your code updates there.

--Bob Yantosca (talk) 16:36, 21 June 2019 (UTC)

Getting updates from the GEOS-Chem repository in to a particular branch

In the previous example, we demonstrated how to pull all remote branch references into your local source code folder. However, this is often not necessary. Very often you will just want to pull updates into a single branch, as demonstrated below.

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

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

(2) View the revision history with Gitk. You will see something similar to this:

GitPullStep1.png

(3) Create a new branch off of master (let's call it feature/MyFeature).

(4) Check out the feature/MyFeature branch (or whatever you named it).

(5) View the revision history again. You should see something similar to this:

GitPullStep4.png

(6) Pull a branch from the remote GEOS_Chem repository into the feature/MyFeature branch:

git pull origin dev/12.4.0

You will see text similar to this:

From github.com:geoschem/geos-chem
 * branch              dev/12.4.0 -> FETCH_HEAD
Updating 8577e970..93e8ad81
Checking out files: 100% (173/173), done.
Fast-forward
 GeosCore/Makefile                          |   14 +-
 GeosCore/RnPbBe_mod.F                      |   33 +-
 ...etc. -- this is the list of files that are being modified ...
173 files changed, 12105 insertions(+), 17449 deletions(-)

Here, git pull origin means to pull the updates from the same repository that your GEOS-Chem source code folder was cloned from. This will almost always be the GEOS-Chem Github repository.

(7) View the revision history again. You will see that the feature/MyFeature branch is now at the same commit as the dev/12.4.0 branch.

GitPullStep5.png

(8) At this point you can make further code edits into the feature/MyFeature branch.

--Bob Yantosca (talk) 16:35, 21 June 2019 (UTC)

Getting updates from a directory other than the remote GEOS-Chem Github repository

In some cases, you might need to pull updates from another user's GEOS-Chem source code directory. To do this, follow Steps 1-4 in the previous section.

Then type:

git pull /path/to/other/Git/repository BRANCH-NAME

This will copy the updates from BRANCH-NAME in the other user's repository into your currently checked-out branch.

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

Further reading

  1. Git pull (Git documentation)
  2. Git pull (Atlassian Git tutorial)
  3. Git pull (FreeCodeCamp)



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