Interfacing HEMCO into GEOS-Chem

From Geos-chem
Revision as of 18:03, 28 July 2014 by Bmy (Talk | contribs)

Jump to: navigation, search

This page is intended for advanced HEMCO developers. Most GEOS-Chem users will not have to use these commands, as the latest HEMCO updates will be included when you clone or pull from the GEOS-Chem repository.

— Bob Yantosca, 28 May 2014

Overview

Christoph Keller wrote:

GEOS-Chem now contains the HEMCO folder as a git subtree. This means that I "outsourced" the HEMCO code into an own git repo and added this repository as a subtree to GEOS-Chem. There are no changes for people working on GEOS-Chem. It is still possible to modify, commit, pull, etc. the entire GC repository including the HEMCO subtree. However, it is now easily possible to update the HEMCO subtree with changes made in the HEMCO source repository, and to synchronize changes made from within the external HEMCO repository. Some more details on the subtree are given below.

Creating a subtree for HEMCO in the GEOS-Chem source code directory

Christoph Keller wrote:

1. Create subtree of HEMCO code in GC repo

cd Code.v10-01                        # or whatever your GEOS-Chem code dir is named
git subtree split -P HEMCO -b export

2. Import subtree into new repo (this is the new HEMCO source code)

cd /home/ckeller/HEMCO/src/
git init
git fetch ../Code.v10-01 export
git checkout -b master FETCH_HEAD

3. Add HEMCO code as new remote to GC

cd Code.v10-01
git remote add hemco /home/ckeller/HEMCO/src/.git
git fetch hemco

4. Remove existing HEMCO code from GC repo

git rm -r HEMCO
git commit -m "Remove HEMCO from GEOS-Chem. Will be imported as subtree"

5. Add HEMCO as subtree

git subtree add -P HEMCO -m "Readded HEMCO as subtree"  hemco/master

Done!

Pulling updates from the external HEMCO repository into GEOS-Chem

To pull the newest changes from the external HEMCO repository into GEOS-Chem, follow these instructions:

cd Code.v10-01    # or whatever your GEOS-Chem code dir is named
git fetch hemco
git subtree merge -P HEMCO --squash -m "merged changes from HEMCO" hemco/master

NOTES:

  1. The -P option specifies the subdirectory of Code.v10-01 into which to pull the updates from the separate HEMCO repository.
  2. The --squash option "squashes" the git history of the source code into a single commit. Otherwise, the full history will be imported.
  3. The -m option specifies the commit message that will show up in the revision history.

--Bob Y. 13:52, 28 July 2014 (EDT)

Pushing changes made to HEMCO in GEOS-Chem back to the external HEMCO repository

If you updated the HEMCO code in GEOS-Chem, and want to send those updates back to the external HEMCO repository, follow this procedure:

To bring changes made in GEOS-Chem (/home/ckeller/geosChem/v10-01c/hemco/Code.v10-01c/HEMCO) into the source code (/home/ckeller/HEMCO/src/):

cd /home/ckeller/geosChem/v10-01c/hemco/Code.v10-01c/
git subtree split -P HEMCO -b update
git push hemco update:master

NOTES:

  1. The -P option specifies the subdirectory of Code.v10-01 into which to pull the updates from the separate HEMCO repository.
  2. The -b lets you specify the branch name in the remote HEMCO repository into which the updates will be sent.

--Bob Y. 13:52, 28 July 2014 (EDT)

References

Here are some helpful articles that describe how the Git subtree process works:

  1. http://psionides.eu/2010/02/04/sharing-code-between-projects-with-git-subtree/
  2. http://makingsoftware.wordpress.com/2013/02/16/using-git-subtrees-for-repository-separation/
  3. http://blogs.atlassian.com/2013/05/alternatives-to-git-submodule-git-subtree/
  4. https://help.github.com/articles/about-subtree-merges
  5. https://hpc.uni.lu/blog/2014/understanding-git-subtree/
  6. http://blog.charlescy.com/blog/2013/08/17/git-subtree-tutorial/
  7. https://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html

--Bob Y. 14:03, 28 July 2014 (EDT)