Introduction to Git

Previous | Next | Guide to using Git with GEOS-Chem | Getting Started with GEOS-Chem | GEOS-Chem Main Page

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 a brief introduction to the Git source code management system.

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.

Git is a distributed source code management system

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.

Git is much simpler to use than CVS and Subversion

1. 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.

Git allows developers to easily do the following things

1. Download the most current GEOS–Chem source code online.
2. Download the most current GEOS–Chem run directories online.
3. Develop and test their source code additions to GEOS–Chem in their own local repository.
4. 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).

Further reading

1. Number one piece of advice for new developers (Codeburst)
2. What is Git and why should I use it? (Quora)
3. Why Git and Github? (Karl Broman)

---

Previous | Next | Guide to using Git with GEOS-Chem | Getting Started with GEOS-Chem | GEOS-Chem Main Page