Version control with Git

Overview

Why use Git?

GEOS–Chem model development is done in a distributed manner. Individual users from several different institutions will download a recent GEOS–Chem version and modify it according to their own particular research interests. When these source code modifications are deemed to be mature, users will then submit them to the GEOS–Chem Support Team for inclusion into the mainline "standard" model.

In the past, the GEOS–Chem source code and run directories were distributed to the user community as a series of TARBALL (i.e. *.tar.gz) files via anonymous FTP. The advantage of this method was that one would only have to download a single file. However, as the number of GEOS–Chem users (and submitted source code modifications) grew, this method became unwieldy. For example, if only a single file needed to be updated, the entire TARBALL file would have to be regenerated. This often became a source of confusion and error.

Given the large number of user code submissions, robust source code management techniques must be employed in order to ensure the integrity of the GEOS–Chem code. Therefore, the GEOS–Chem Support Team has selected the Git version control software for GEOS–Chem source code management.

Advantages of using Git

Git offers many improvements over previous source code management software such as CVS and Subversion.

1. Git avoids some of the limitations of CVS (which is by now 20-year-old software).
   • Git is a distributed source code management system. Instead of having one central GEOS–Chem repository residing on a single server, Git allows you to keep an identical copy (a.k.a. "clone") of the GEOS–Chem source code repository on your own system. Having several copies of the GEOS–Chem repository allows for redundancy in case of catastrophic server failure or other such calamity.
   • Modifications that you make to your own repository will not affect the repositories of other users. (That is, unless you consciously decide to "push" your changes to another repository).
   • When you are ready to submit your source code modifications for inclusion into the "standard" code, the GEOS–Chem Support Team can simply get them with a Git "pull" operation.
   • Git allows you to save out your source code changes to a "patch" file (a text file with a list of source code differences). This can be emailed to other users and applied to their local source code repository.
     
     
2. In general, Git is much simpler to use than CVS.
   • With Git, you can "pull" changes from other users directly into your own local source code repository.
   • With Git, you can easily create several branches off of code development of the "master" branch. (Branching was always problematic in CVS).
     • Each branch can hold a new "feature", which may be tested independently of the rest of the code.
     • Branches can be merged back into the "master" branch when the new feature has been validated.
   • The Git repository browser, called GitK, allows you to see every single line of code that has been modified, going all the way back to the start of the project.
   • A graphic user interface, called the Git Gui, lets you control Git in a visual manner rather than using command-line options.
     
     
3. With Git, GEOS–Chem developers are able to:
   • download the most current GEOS–Chem source code online.
   • download the most current GEOS–Chem run directories online.
   • develop and test their source code additions to GEOS–Chem in their own local repository.
   • submit their mature source code updates back to the GEOS–Chem Support Team for inclusion in the standard mainline code (via "Git pull" or patch files).

Tutorials about Git

Here are some useful resources for learning the various Git commands:

For beginners

GitRef.org (the Git Reference)

An overview of the basic Git commands.

Git tutorial video

Excellent lecture given by Bart Trojanowski for the Ottawa Group of Ruby Enthusiasts. HIGHLY RECOMMENDED!

Git for Designers

Nice overview of how version control works. Recommended for people with no prior experience using a version control system.

Git for the Lazy

This is an excellent Git guide for beginners. Short, sweet, and to the point.

Overview of Git and Subversion

Presentation given by the School of Engineering and Applied Sciences at Harvard.

For more advanced users

ProGit

Excellent online book that discusses many of Git's features, and how to use them like a pro.

Git From the Bottom Up by John Wiegley

Article which not only describes the commands used to invoke Git but also the design philosophy behind the Git version control system. Good theoretical background but somewhat terse for beginners to understand.

Official Git tutorial

A comprehensive but somehwat terse tutorial of Git commands.

GitMagic

Descriptive online book that goes into the nitty-gritty of Git usage. A worthwhile read!

Git for CVS Users

A tutorial specifically geared toward migrating from CVS to Git.

Sending Patches with Git

A guide how to use the patch feature of Git to send your changes to another user.

How to create and apply a patch with Git

Another nice explanation of how to use Git to send patch files.

Using Git with GEOS-Chem and GAMAP

Obtaining and installing Git

If you don't already have Git on your system then you (or your sysadmin) will have to install it. To check if it is already installed, you can ask for the version at the Unix prompt. Type:

[534 rhea GEOS_5]% git --version

If you get a string similar to:

git version 1.6.6.2

then you are good to go. (The actual version # doesn't matter.) If not, then you (or your sysadmin) may obtain the Git source code (or binaries) the Git website.

First-time setup

Before using Git for the first time, you need to set up your ~/.gitconfig file. Open a text editor and then cut & paste the text from this sample .gitconfig file. Then save it as ~/.gitconfig.

Be sure to change your name and email accordingly, this is how Git will know who you are!

Please see the following pages which describe how to download the GEOS-Chem and GAMAP source code packages via Git.

Downloading GEOS-Chem and GAMAP

Please see the following wiki pages which contain detailed information about how to use Git to download and modify the GEOS-Chem and GAMAP source code packages:

• Using Git with GEOS-Chem
• Using Git with GAMAP

--Bob Y. 09:43, 16 March 2010 (EDT)

References

1. Git web page
2. Git Cheat Sheet
3. Google "Tech Talk" by Linus Torvalds, the creator of Git (Video on Youtube)
4. Google "Tech talk" by Randal Schwartz (Video on Youtube)
5. Setting up your .gitconfig file (Link)

--Bob Y. 15:35, 26 January 2011 (EST)