Advanced Git usage

From Geos-chem
Revision as of 20:30, 5 August 2019 by Bmy (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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


On this page we discuss how some of the more advanced things you can do with Git.

Resetting a branch of your local source code folder to an earlier state

If you would like to abandon work on a branch and restore that branch to an earlier commit, you can use Git's hard reset option. This is best done with the Gitk browser.

NOTE: You should do a hard reset on branches of your local source code folder, and not on the remote repository.

(1) Change to your GEOS-Chem source code directory.

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

(2) Start Gitk.

gitk --all &

(3) View the revision history in the top-left Gitk window.


In this example above, the feature/MyFeature branch is checked out, and has some unstaged changes. These are updates that have not been committed yet.

(4) Let's say that you want to abandon the work that you have done in feature/MyFeature branch. This may be because you have added a bunch of debugging print statements into the code, but no longer need them. Let's also assume that you want to reset feature/MyFeature to the same commit as the master branch.

Right-click on the commit corresponding to the master branch. A context menu will appear.

(5) Click on the menu item Reset the feature/MyFeature branch to here.


(6) A dialog box will appear with 3 radio buttons. Click on Hard: reset working tree and index (discard all changes).


(7) Click on OK.

(8) View the revision history again and Refresh Gitk by either pressing F5 or selecting File/Update from the dropdown menu.

You should now see this:


Note that the unstaged changes have now disappeared, and that feature/MyFeature is now at the same commit as master.

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

Reverting to an older state of the code

When you clone GEOS-Chem from the remote repository to your local disk space (with the git clone command), the master branch will point to current stable GEOS-Chem version. However, you may want to revert to an older state of the code. Git allows you to do this very easily.

Let's assume that the latest version of the code is 12.3.2 but that you want to use version 12.0.0. The procedure is as follows:

(1) Change to your local GEOS-Chem source code folder.

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

(2) Start Gitk.

gitk --all &

(3) View the revision history with Gitk.

(4) Locate the commit in the revision history window corresponding to version 12.0.0. This should be marked with a yellow tag.

(5) Right-click with the mouse on the name of the commit. A context menu will appear.

(6) Select the Create new branch menu item. A dialog box will appear.

(7) Type the name of the new branch. For this example, use the name dev/12.0.0

That's it. You now have two branches:

  1. master represents the current stable version (in this example, 12.3.2)
  2. dev/12.0.0 represents GEOS-Chem version 12.0.0

Also note: Using this method, you can check out a new branch from any commit, not just those commits that correspond to GEOS-Chem releases.

Cherry-picking individual commits from another branch

Git allows you to cherry-pick commits, that is to pull a single commit from a different branch into the branch you are currently working on. This can prove useful in many situations. For example, a colleague may have committed a critical bug fix into his or her development version of GEOS-Chem. You may want to only grab that particular bug fix into your current branch without also getting all the other changes that your colleague made.

The best way to cherry-pick commits is via the gitk browser Here is a simple example. Let's assume the following:

  1. You're working in branch my_branch of your local GEOS-Chem code directory.
  2. You've pulled the branch containing your colleague's bug fix update into a new branch of your local code directory called Bug-fix-branch.
  3. You are only interested in merging the commit labeled "Remove obsolete LAVHRRLAI and LMODISLAI from input.geos" into my_branch.

(1) Start Gitk.

gitk --all &

(2) View the revision history in the upper-left Gitk window:

Cherry pick 1.jpg

As you can see, my_branch is displayed in boldface, which indicates that is the current checked out branch.

(3) Locate the commit entitled "Remove obsolete LAVHRRLAI and LMODISLAI from input.geos" in the revision history window.

(4) Right-click with them mouse on the commit entitled "Remove obsolete LAVHRRLAI and LMODISLAI from input.geos".

(5) A context menu will appear. Select the Cherry-pick this commit option:

Cherry pick 2.jpg

(6) View the revision history in the upper-left Gitk window again:

Note that my_branch now displays higher than Bug-fix-branch in the gitk browser revision history window, because it now has the most recent commit.

Cherry pick 3.jpg

If the commit that you brought into my_branch comes from a base version of GEOS-Chem that is significantly different than the your version, he cherry-pick operation may generate conflicts that you will have to manually resolve.

--Bob Yantosca (talk) 17:03, 21 June 2019 (UTC)

Removing references to remote branches

In a previous section, we learned how to pull references for branches at the remote repository into your local source code folder. But when branches are deleted from the remote repository, you will likewise want to delete the references to those branches as well. Here's how to do it.

(1) Start Gitk.

gitk --all &

(2) View the revision history in the top-left GitK window.


(3) Let's assume that you want to remove the reference to the remote branch remotes/origin/feature/N2O5_hetchem branch, as you don't need this anymore. Type:

git branch -r -d origin/feature/N2O5_hetchem

(4) Refresh the revision history display in GitK by pressing F5, or by selecting File/Update from the menu.


As you can see, the remotes/origin/feature/N2O5_hetchem branch has now been deleted.

Further reading

  1. Advanced Git tutorials overview (Atlassian Git tutorial)
  2. The Advanced Git Guide (Toptal)
  3. Advanced Git commands you will actually use (Stosb)
  4. Advanced Git usage (Richard K. Darst)
  5. Learn enough Git to be dangerous (Michael Hartl)

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