ROMS git

Tutorial: Installing ROMS via git

I would like to explain how and why one would install ROMS via git-svn.

What is git?

Git is a distributed version control system available from [1]. That site also contains links to documentation and other resources - even videos! As a distributed system, any copy you make of a repository is complete unto itself, with history and possibly branches. If you download ROMS via git-svn, you now have an environment in which you can save your own changes, create new branches, and keep a history of what you have tried.

As a ROMS developer, I have write access to a branch at the Rutgers svn server, but that's not true of most users. As ROMS users, you still have opportunity to create and modify ROMS files that you might want to manage with some sort of versioning software. This is not easy with svn, in which each "sandbox" can only point to one repository. You've got to have one pointing to the myroms.org site in order to get updates. Then the easiest (but unsatisfactory) way to back up your changes is via tarball.

Prerequisites

You will need:

• svn
• git
• some Perl scripts which come with svn, but aren't always installed
• Perl

If everything is there and you are in a git sandbox, you can have this sort of exchange:

% git svn --version
git-svn version 1.7.1 (svn 1.6.5)

If everything is there and you are not in a git sandbox, you get this instead:

% git svn --version
fatal: Not a git repository (or any of the parent directories): .git
Already at toplevel, but .git not found
at /Users/kate/libexec/git-core/git-svn line 276

If the Perl scripts are not there, you get something more like:

% git svn --version
Can't locate SVN/Core.pm in @INC (@INC contains: /u1/uaf/kate/...

You might have the best luck with package managers rather than installing from source code.

Procedure

For the Hong Kong training, Dale asked me to set up the CIRCLE test problem, in three different flavors. I did so, but the initial conditions require the use of a C language Bessel function, changing the link rules for ROMS. This is the perfect example of why you would want to be able to create alternate branches. What I am going to lead you through here is setting up three branches:

• master, a copy of the myroms.org trunk
• circle, a branch with the special features of the CIRCLE problem
• my_stuff (or whatever name you like), a place to put your own changes

Setup

git config --global user.name “me”
git config --global user.email “me@work”
git config --global color.ui “auto”

For the first two, substitute "me" with your real name in quotes and "me@work" with your real email address. The third is entirely optional, but provides more colorful output from git. For all, leave out the "--global" argument to have it apply to the current directory only. As it is, it will put information into a .gitconfig file in your home directory.

Downloading ROMS

We want to download a specific revision of ROMS rather than the entire history. As I write this, the current revision (visible at [2]) is 529. A recent prior version is 526, from just after the annual changing of the Copyright notice in all files. I'd like to fetch something just before the current version so you can see the update and merge procedures. Grabbing rev 526:

git svn clone –r 526 --username name https://www.myroms.org/svn/src/trunk [MyDir]

Here, "--username name" is not needed if your ROMS userid is the same as your userid on the local computer, "name" being your ROMS name. If you leave off the MyDir argument, it will create a directory called "trunk".

Now you can change into the directory called MyDir or trunk and see all the ROMS directories. There will also be a hidden directory called ".git". One file there that's useful to look at is .git/config, containing information about other repositories it knows about. Since we haven't told it about other remote sites yet, it should look something like:

[core]
repositoryformatversion = 0
filemode = true
bare = false
logallrefupdates = true
ignorecase = true
[svn-remote "svn"]
url = https://www.myroms.org/svn/src/trunk
fetch = :refs/remotes/git-svn

Ignoring Files

Let's create a ".gitignore" file:

e% cat > .gitignore
Build
ocean?
core*

We can add this to the list of files to be tracked by git:

% git add .gitignore
% git commit -m "adding .gitignore"

Without the "-m string" option, it will open up a text editor, waiting for a description for this commit.

Creating Branches

As we said above, we would like to have three branches at the end, one containing some code for a CIRCLE test problem. Let's start off with that:

% git branch circle
% git checkout circle
% git branch

This last command should just show that we are now in the circle branch:

* circle
master

Now to fetch the circle code from [3]. From the trunk directory, we can apply these changes to the circle branch:

% gunzip Circle.diffs.gz
% patch -p1 < Circle.diffs

We can see what we have with "git status":

% git status
# On branch circle
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: Master/Module.mk
# modified: ROMS/Modules/mod_scalars.F
# modified: ROMS/Utility/checkdefs.F
# modified: ROMS/Utility/def_info.F
# modified: ROMS/Utility/wrt_info.F
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# Apps/
# makefile.circle
no changes added to commit (use "git add" and/or "git commit -a")

A "git commit -a" will add the updates to all the files that git is already tracking. For this case, we want it to track a couple of new things:

% git add Apps makefile.circle

Now we can commit the whole works:

% git commit -a -m "Circle problem"

When in this branch, one can run any of the three Circle cases:

• CIRLCE_BOX - a square grid with masking
• CIRCLE_ROUND - requires an external circular grid
• CIRCLE_POLAR - a donut-shaped domain

If you use build.bash, edit the line near the bottom invoking "make" and change it to "make -f makefile.circle".