GEOS–Chem v9–02 Online User's Guide
Previous | Next | Printable View (no frames)
8. Using Git to manage the GEOS–Chem source code
In this chapter we list the Git commands that you will most commonly use to manage your local GEOS–Chem repository. For more information (including information about installing Git on your system), please see:
8.1 Viewing the revision history
Use the gitk viewer to examine the contents of your Git-backed GEOS–Chem source code directory. You have two choices:
Change into the Code.v9-02 directory and start gitk as follows:
cd Code.v9-02
gitk --all & # This will show ALL open branches
At the top left of the gitk screen, you will see the graph of revisions. Each dot represents a commit, along with the log message that accompanied each commit. Note that the most recent commit (i.e. the line at the very top), there are 2 green boxes at the top, one named master and one named origin:
origin: Therefore, this indicates the "pristine", unchanged code that you got from the download.
master: This represents the current state of your local repository. Because you haven't done anything to the code yet, the master and origin branches both point to the same commit.
If you click on any of the commits in the top left window, in the window below, you will see the log message and a list of changes to the source code. The old code is marked in RED and the new code is marked in GREEN. At right you will also see a list of files that were changed during the commit.
So you can easily see how the code has evolved by using gitk.
Use the git gui for source code management. Start this in your Code.v9-02 directory:
cd Code.v9-02
git gui &
On the left there are 2 windows:
Unstaged Changes: Git is telling you that it doesn't recognize these changes as belonging to the repository. If you modified any files since the last commit, you will see them displayed here. Right above this window you will find the name of the current checked-out branch.
Staged Changes: Git will add these changes to the repository the next time you make a commit.
Whenever you need to modify the source code, you should NOT do it on the master branch. Create a new branch for your modifications. Test your modifications in the new branch ad nauseum until you are sure that everything is functioning as it should. When you are done merge your new branch back into the master branch. You can then delete the branch you were testing in.
If you ever need to start over from scratch, you can just go back to the master branch and you will get back the state of the code before your modifications were added. This will save you time.
To create a new branch, go to the Branch/Create on the menu (or type CTRL–N). You will get a dialog box that prompts you for the new branch name. Type a unique name and then click Create.
You should pick names that have meaning to you. For example, some good branch names are:
You will be automatically placed into the branch you have just created.
With Git, you should commit frequently, such as when you have completed making revisions to a file or group of files. Commits that are made on one branch will not affect the other branches.
Committing is best done with the git gui. Follow these steps:
Pick Commit/Rescan from the menu (or type the F5 key). This forces the git gui to show the latest changes.
You should see a list of files in the Unstaged Changes window. Clicking on the icon at the left of a file will send it to the Staged Changes window. Git will add all of the files in Staged Changes to the repository the next time you commit. Note: Clicking on the icon of the files in the Staged Changes moves back the file to the Unstaged Changes window.
Type a Commit message in the bottom right window. See this example of a good commit message. Some pointers are:
You will see two radio buttons above the Commit message window. Specify the type of commit:
Click on the Commit button.
Then if you start the gitk viewer, your new commit should be visible.
8.2.4 Switching between branches
Before you switch from one branch to another (aka "checking out a branch"), commit any remaining unstaged files to the current open branch. Unstaged files will remain in your working directory even after you checkout a different branch. This can will lead to confusion.
To check out a new branch, go to Branch/Checkout on the menu and pick the name of the branch you would like to switch to. The current branch name will be displayed just below the menu at top left.
Once you have created your branch and have checked it out, you can start modifying it with your favorite text editor. (We recommend Emacs.)
We recommend to keep one open branch per new feature that you are adding into GEOS–Chem. This lets you test each individual feature separately. After you have validated each feature, you can merge its branch back into the master.
Follow this procedure to merge your changes back into the master branch:
Switch back to the master branch by selecting Branch/Checkout from the menu (or type CTRL–O). You will be given a dialog box of available branches. Select master and click Checkout.
Pick Merge/Local Merge from the menu (or type CTRL–M). You will be given a dialog box of available branches. Select the branch you would like to merge into master and click Merge.
This should merge your changes back into master. Then if you start the gitk viewer, the you should see your changes in the master branch.
Git lets you tag a particular commit with an alphanumeric string for easy reference. This tag will allow users to just refer to the tag name using git pull.
Tagging can be done in one of two ways. You can add a tag via the command line:
git tag GEOS-Chem v9-02a git tag GEOS-Chem v9-02b
etc. at the Unix command line.
You may also add a tag via the gitk viewer utility, as follows:
Open the gitk browser:
In the top-left window select a commit by clicking on it with the mouse
Right-click to pull up the context menu. Select the Create tag option.
Type in your tag text and click Create.
To remove a tag, you can use the git tag command directly:
git tag -d TAG_NAME
Where TAG_NAME is the name of the tag that you have added.
NOTE: Tagging is something that typically only the GEOS–Chem Support Team will do.
Once you have merged your changes back into the master branch, you can delete the branch you just created. In the git gui, go to the Branch/Delete menu item. Select the name of the branch that you wish to delete from the dialog box display.
8.3 Sharing your revisions with others (and vice-versa)
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 obviates the need of having to merge differences between codes manually.
8.3.1 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, type:
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 by typing:
git format-patch -3 --stdout > my-patch-file.diff
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.
8.3.2 Checking the validity of a patch file
Other users can 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, use the git apply command:
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 will do. For more detailed information about the patch, you can open it in either an emacs or vi window and examine it manually.
You can also use git apply command to determine if the patch will install properly or not. Type:
git apply --check my-patch-file.diff
If an error occurs, it usually means that the patch was made from an earlier version of GEOS–Chem. You can rectify this by having the sender recreate the patch with the most recent GEOS–Chem version.
8.3.3 Reading a patch file into your local repository
To ingest a patch file into your local Git repository, first make a new branch. Then follow this procedure:
Pick Branch/Create from the menu (or type CTRL–N). Give your branch a descriptive name like "Updates_from_xxxx" that will serve as a mnemonic.
Pick Branch/Checkout from the menu (or type CTRL–O) and switch to the branch you just created.
To ingest the other person's source code changes, type:
git am < their-patch-file.diff
You can then test the other person's revisions in the separate branch until you are sure they are OK. Then you can merge them back into the master branch as described above.
For more information about Git patch files, please see the following links:
8.4 Getting updates from the remote repository
We recommend that you use the the git clone command to download each newly-released GEOS–Chem version into a new local directory.
There may be times, however, when "patches" (i.e. minor fixes) 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:
Change to your local code directory (e.g. Code.v9-02)
Make a new branch named patch (or something similar).
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, as follows:
git pull git://git.as.harvard.edu/bmy/GEOS-Chem master
Test compilation to make sure everything is fine.
Check out the master branch.
Merge the patch branch into your master branch.
Delete the patch branch.
This will merge the changes from the master branch of the remote repository into your master branch.
8.5 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 repository will point to the most recent commit. 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 v9–02, but that you want to use the version v8–03–01. The procedure is as follows:
Clone GEOS–Chem with:
git clone git://git.as.harvard.edu/bmy/GEOS-Chem Code.v9-02
Open the gitk browser by typing gitk --all & at the command line.
In the top-left window of gitk, find the commit that you want to revert to. Usually this will be denoted with a yellow tag (e.g. v8–03–01 or v8–03–01–benchmark). However, if there are any post-release patches, be sure you select the oldest one.
Right click with the mouse. This will open a context menu. Select Create new branch.
A new dialog box will pop up asking you to name the branch. Type Code.v8–03–01 and click Create.
Close gitk and open the git gui by typing git gui &.
From the git gui dropdown menu, select Branch / Checkout, and then pick Code.v8–03–01.
That's it! We now have two branches that represent different GEOS–Chem versions.
The master branch represents the state of the code as of the v9–02 release.
The Code.v8–03–01 branch represents the state of the code as of the v8–03–01 release.
You can work on the Code.v8–03–01 branch as you wish. You can create further branches off of the Code.v8–03–01 branch. You can always revert to the v9–02 state of the code by just switching back to the master branch (with Branch / Checkout from the git gui dropdown menu).
Previous | Next | Printable View (no frames)