Using Git with GAMAP

From Geos-chem
Jump to: navigation, search

This page describes how to use the Git version control system to download and manage the GAMAP source code package.

Obtaining and installing Git

You will need to make sure that Git is installed on your system. Please see this wiki post for more information.

Downloading GAMAP

Initial download

The GAMAP source code repository has now been migrated from CVS to Git, and is now available for remote download. However, you should make a backup of your existing GAMAP code before you download the GAMAP code from the Git repository.

Like most GAMAP users, you probably have been storing the gamap2/ directory in a subdirectory of your ~/IDL/ directory. So let's rename the existing GAMAP directory:

cd ~/IDL
mv gamap2 gamap2.backup

This will allow us to revert to the old code in case there is a problem w/ the Git download.

Once the existing directory has been backed up, you can then proceed to download the GAMAP source code from the Git online repository.

Users should use:

git clone https://bitbucket.org/gcst/gamap2

This will create a "clone" of the gamap2/ directory, which will be populated with the GAMAP source code subdirectories. The various system files are all stored in the gamap2/.git subdirectory. The files in gamap2/ are an exact copy of what was on the Git repository server at the time you downloaded it.

If you wish to use a different directory name for your local "cloned" repository, you may type it as the second argument to git clone, e.g:

git clone https://bitbucket.org/gcst/gamap2 new_gamap2

However, we recommend that your local repository be named the same as the remote repository.

NOTES:

  1. You only need to "clone" the repository the first time you download it to your system. To get further updates from this repository, you will use a different command.
  2. Once you are sure that the repository was downloaded properly, then you may either archive or discard the gamap2.backup directory.

Ignoring files

Git also allows you to ignore certain types of files that we don't need to track (e.g. autosave files *~).

You can tell Git that you don't want these files to be tracked by editing the .git/info/exclude file in your source code directory. Open this file in your favorite text editor and edit it to look like this:

# git-ls-files --others --exclude-from=.git/info/exclude
# Lines that start with '#' are comments.
# For a project mostly in C, the following would be a good set of
# exclude patterns (uncomment them if you want to use them):
*~

Viewing the revision history

The best way to examine the contents of your Git-backed GAMAP source code is to use the gitk viewer. There are two ways to do this:

(1) Change into the gamap2/ directory and start gitk as follows:

cd gamap2/
gitk &

(2) Or if you are using the git gui GUI browser (more on that below), you can invoke gitk from the Repository/Visualize master's History menu item.

At the top left of the gitk screen, you will see the graph of revisions. In the case of GAMAP, this is pretty simple, as all revisions were checked in linearly (i.e. there was no branching). 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
This was the state of the repository on the remote server when you checked it out. So this is the "pristine", unchanged code that you got from the download.
master
This is the current state of the local repository now. Since we haven't done anything to the code yet, the master and origin 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 it's really easy to see how the code has evolved with gitk.

Making revisions

Using the GUI browser

We recommend using the git gui for source code management. Start this in your gamap2/ subdirectory:

cd gamap2
git gui &

On the left there are 2 windows:

Unstaged Changes
An unstaged change is a modification that Git does not know about yet. If you modified any files since the last commit, then they should be displayed in this window. Also, right above this window you will find the name of the current checked-out branch.
Staged Changes
These are changes that Git will add to the repository the very next time you make a commit.

In general, anytime you need to modify the source code, you should NOT do it on the master branch. You should create a new branch for your modifications. Then you can test your modifications ad nauseum until you are sure that everything is functioning as it should. When your modifications are complete, you can merge them back into the master branch. Then the branch you created can be deleted.

The advantage of this approach is that 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.

Creating branches

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

You should pick names that have meaning to you. Some good branch names are:

  • Bug_fixes
  • Color_table_update
  • Timeseries_plots

etc. To switch between branches, 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, then you may begin making modifications to the source code.

Committing

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 in the git gui. Basically you follow these steps:

  1. To force the git gui to show the latest changes, you can pick Commit/Rescan from the menu (or type the F5 key).
  2. You should get a list of files in the Unstaged Changes window. Clicking on the icons on the left of the file names will send them to the Staged Changes window. Once they are in the Staged Changes this means that Git will add them to the repository on the very next commit. Note: Clicking on the icon of the files in the Staged Changes moves back the file to the Unstaged Changes window.
  3. Type a Commit message in the bottom right window. See this example of a good commit message. Some pointers are:
    1. The first line should only be 50 characters or less and succinctly describe the commit
    2. Then leave a blank line
    3. Then add more in-depth text that describes the commit
    4. Then click on the Signed-off by button. This will add your name, email address, and a timestamp.
  4. There are two radio buttons above the Commit message window.
    1. New commit: This is the default. Assumes we are making a totally new commit.
    2. Amend last commit: If for whatever reason we need to update the last commit message, pick this button.
  5. Then when your commit message is done, you can click on the Commit button.

Then if you start the gitk viewer, your new commit should be visible.

Merging

Make a patch file before merging

Before you merge your changes back into the mainline master branch, consider making a patch file. This is a file that contains the differences between your current branch and the master branch. Please see the section creating a patch file to share with others below.

Doing the merge

When you are ready to merge your changes back into the mainline master branch, then you can follow this procedure.

  1. 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 press OK.
  2. From the menu, pick Merge/Local Merge (or CTRL-M).

This should merge your changes back into master. If you then use the the gitk viewer, then the merge you just made should be visible.

Tagging

Git also allows you to tag a commit with an alphanumeric string for easy reference. This tag will allow users to just refer to the tag name using git clone or git pull.

Tagging is best done outside of the git gui. You can just type:

git tag GAMAP_v2-14

at the Unix command line.

Deleting branches

Once you have merged your changes back into the master branch, you may delete the branch you just created. In the git gui, go to the Branch/Delete menu item. You will be given a dialog box where you can select the name of the branch you wish to delete.

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 totally obviates the need of having to merge differences between codes manually.

Creating a patch file to share with others

To create a patch file containing the differences between a branch of your code with your master branch, type the following text:

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.

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

Reading a patch file into your local repository

Other users can also send you their source code revisions as patch files. To ingest their changes into your local Git repository you should first make a new branch. Follow this procedure:

  1. 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.
  2. Pick Branch/Checkout from the menu (or type CTRL-O) and switch to the branch you just created.
  3. 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.

Getting updates from the remote repository

If you want to get the latest changes from the remote repository (e.g. bug fixes, new versions, etc), you have to use the git pull command from the gamap2 directory.

The safest way to proceed is to make a new branch and check it out. The updates from the repository will be then sent into this branch. We'll name this branch from_remote, to denote that this will contain the source code update from the remote repository.

Once you have created and checked out the from_remote branch, we can use git pull to send the changes from the remote repository into from_remote.

Users should type:

cd ~/IDL/gamap2
git pull https://bitbucket.org/gcst/gamap2 master

This will bring the latest changes from the master branch back into your from_remote branch. You can then test the source code changes in your from_remote branch to make sure that everything is OK. Then you can merge the from_remote branch back into your master branch as described above. Then once all is well, you may delete the from_remote branch.

--Bob Y. 11:23, 16 March 2010 (EDT)

In summary

We recommend using the git gui because of its user-friendly interface. The following operations are best done from the GUI interface:

  1. Creating and checking out branches
  2. Committing code
  3. Merging code
  4. Deleting branches
  5. Examining revision history (you may also use gitk as standalone)

The following operations are best done from the command line:

  1. git cloneInitial download of repository
  2. git push:  Send changes to a remote repository
  3. git pullGet changes from a remote repository
  4. git tagAttach a label to a particular commit
  5. git format-patchCreate a patch

--Bob Y. 10:23, 19 March 2010 (EDT)