Using Git with GAMAP
This page describes how to use the Git version control system to download and manage the GAMAP source code package.
- 1 Obtaining and installing Git
- 2 Downloading GAMAP
- 3 Viewing the revision history
- 4 Making revisions
- 5 Sharing your revisions with others (and vice versa)
- 6 Getting updates from the remote repository
- 7 In summary
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.
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.
- 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.
- Once you are sure that the repository was downloaded properly, then you may either archive or discard the
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:
- 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.
- 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.
Using the GUI browser
We recommend using the git gui for source code management. Start this in your
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.
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:
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.
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:
- To force the git gui to show the latest changes, you can pick Commit/Rescan from the menu (or type the F5 key).
- 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.
- Type a Commit message in the bottom right window. See this example of a good commit message. Some pointers are:
- The first line should only be 50 characters or less and succinctly describe the commit
- Then leave a blank line
- Then add more in-depth text that describes the commit
- Then click on the Signed-off by button. This will add your name, email address, and a timestamp.
- There are two radio buttons above the Commit message window.
- New commit: This is the default. Assumes we are making a totally new commit.
- Amend last commit: If for whatever reason we need to update the last commit message, pick this button.
- 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.
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.
- 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.
- 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.
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.
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.
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
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:
- 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.
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
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)
We recommend using the git gui because of its user-friendly interface. The following operations are best done from the GUI interface:
- Creating and checking out branches
- Committing code
- Merging code
- Deleting branches
- Examining revision history (you may also use gitk as standalone)
The following operations are best done from the command line:
git clone: Initial download of repository
git push: Send changes to a remote repository
git pull: Get changes from a remote repository
git tag: Attach a label to a particular commit
git format-patch: Create a patch
--Bob Y. 10:23, 19 March 2010 (EDT)