Git

Git

ROMS source code is distributed using both Git and Subversion(SVN). The Git repository includes the full history of changes to the ROMS source code. Details on using Subversion can be found here. There are command line and GUI Git clients available for nearly every operating system and a list of popular clients can be found here. This page will help you get started with downloading ROMS with Git.

Note: For instructions using the deprecated and soon to be discontinued myroms.org git repository, click here.

Git Overview

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. All the ROMS/TOMS files are stored in a Git repository on github.com.

This Git repository is the official version of the code which only the developers are allowed to change. Users should download the ROMS code to their local machines using a git client. Don't attempt to use a regular web browser to browse or download files from the Git repository - there are much better tools for interacting with the code repository.

We strongly recommend users always check out the current develop version since this has the most recent updates and bug fixes. The tags are kept largely as a historical record of stable releases at the conclusion of major code upgrades.

If you are making changes of your own, keep them in a separate branch, leaving the develop branch to track changes from the source. Git makes it so much easier to manage your own modifications than svn for those of us without write permission on the repository.

Below is a general description of how Git works. Please look at the Pro Git book for more detailed information. We have not yet tried any GUI clients but may add brief how-tos for the most popular GUIs at a later date.

Configuring GIT

Before downloading any of ROMS repositories, ensure that your ~/.gitconfig has the appropriate git-lfs configuration for correctly downloading some roms_test input and observation NetCDF files. Otherwise, the Test Cases requiring input NetCDF files will fail. The Git LFS is a command line extension and specification for managing large files with Git. A sample of the configuration file looks like this:

more ~/.gitconf

[User]
name = GivenName MiddleName FamilyName
email = your@email
[credential]
helper = cache --timeout=7200
helper = store --file ~/.my-credentials
[filter "lfs"]
clean = git-lfs clean -- %f
smudge = git-lfs smudge -- %f
process = git-lfs filter-process
required = true

Alternatively, you may execute git lfs pull at your location of this repository to download a viable version of the Git LFS files from the remote repository in GitHub. Also, to automatically add the LFS filter to your existing ~/.gitconfig, you could use git lfs install from anywhere in your computer directories.

Downloading ROMS

WARNING: It is strongly suggested that you clone the ROMS source code using the same operating system you wish to compile and run ROMS on. If you download the code on a Windows machine and wish to run it on a non-Windows machine you will need convert the line endings with a utility like dos2unix or recode. Even with these utilities you may still have problems compiling ROMS.

In order download source code from a git repository, git client software must be installed on your local machine. Most Linux distributions come with git, so shell commands may be used without installing additional software. The general form of git commands is:

   git action <repository>

To check-out the files from the ROMS repository develop (latest version), enter (notice https instead of http):

   > git clone https://github.com/myroms/roms.git MyDir

where MyDir is the destination directory on your local computer. It will be created if not found. If MyDir is omitted the code will be downloaded to a directory named roms. You only clone once because Git will keep track of the source, destination and a bunch of other information. For more detail on command line use and syntax, see the Pro Git book.

The idealized and realistic ROMS Test Cases and the Matlab processing software can be downloaded from:

   > git clone https://github.com/myroms/roms_test.git 
   > git clone https://github.com/myroms/roms_matlab.git

We highly recommend that Users clone all the ROMS repositories from the same root directory in their computer and define the ROMS_ROOT_DIR variable in their computer shell login environment, specifying where the User cloned/downloaded the ROMS source code, Test Cases, and Matlab processing software. That is, use the value of pwd from the computer directory where you executed git clone https://github.com/myroms/roms.git

For bash shells:

   export ROMS_ROOT_DIR=MyDownlodLocationDirectory

For csh/tcsh shells:

   setenv ROMS_ROOT_DIR  MyDownlodLocationDirectory

The build scripts will use this environmental variable when compiling any of the ROMS Test Cases without the need to customize the location of the ROMS source code. Also, it is used for loading the path of Matlab scripts in the startup.m configuration file.

Synchronizing Git and SVN revision information

In order to synchronize the Git and Subversion repository revision information, we have created a Git filter that will insert the git hash of the last time a file was modified, similar to the Subversion $Id$ keyword. In order for the filter to work, it has to be explicitly enabled by the user. After the git clone command from above completes change into MyDir and execute the following:

   > git config filter.id.smudge ".git_filters/id.smudge %f"
   > git config filter.id.clean ".git_filters/id.clean %f"

In order to get the Git Id hashes to fill in, you will need to force the smudge filter to run on the source code you have already downloaded. This takes several minutes but only needs to be done once. For bash shells execute:

   > rm .git/index
   > git checkout HEAD -- "$(git rev-parse --show-toplevel)"

For csh/tcsh shells execute:

   > rm .git/index
   > git checkout HEAD -- "`git rev-parse --show-toplevel`"

If you look at the top of any ROMS source file downloaded from the git repository, you will see both the Git commit hash for the last time that file was modified and the corresponding SVN revision properties. For example, the first few lines of ROMS/Modules/mod_ncparam.F look like this:

#include "cppdefs.h"
MODULE mod_ncparam
!
!git $Id: b42658ab652647fca27d50af4afa15c3401fe544 $
!svn $Id: mod_ncparam.F 968 2019-06-17 16:02:48Z arango $
!================================================== Hernan G. Arango ===
! Copyright (c) 2002-2019 The ROMS/TOMS Group  !
! Licensed under a MIT/X style license  !
! See License_ROMS.txt  !
!=======================================================================

You can then use the 40 character (hexidecimal) Git hash to show more information about that code update:

> git show --name-only b42658ab652647fca27d50af4afa15c3401fe544

While you are getting your configuration in order, you also want to tell git who you are:

  > git config --global user.name "your name"
  > git config --global user.email "your@email"

This is important if you plan to ever commit your own modifications.

Several GUI front-ends to Git exist, allowing the user to have visual prompts to help them manage their files and credentials.

Updates

Now and again, you might feel the urge to get up to speed with the latest changes that have been made to the ROMS repository. When that happens, simply go to the directory that was "MyDir" above and type:

   > git pull

Git will remember where you checked out from before and see if a newer revision exists. If so, it will download and apply all the relevant changes.

Managing Your Own Modifications

This assumes that you have a fresh clone of the myroms repository on the develop branch. You want to keep develop' as a pure copy of the source version and keep your own changes in say the arctic branch. Start by creating a branch and switching to it:

> git branch arctic
> git checkout arctic

Now you can make whatever modifications you like (and test them out). To see what changed, you can use git status and git diff. To save your changes, do a:

> git commit -a

Though if you add new files you will have to git add them first.

Getting the Updates

It is easy to fetch and merge the updates. Start by making sure your directory has been cleanly checked in with git status. Then you can update your develop branch:

> git checkout develop
> git pull

Then bring the changes into your arctic branch:

> git checkout arctic
> git merge develop

This will bring in everything that changed since your last git pull, so you might find it easier to keep on top of things by doing this often, not putting it off for years. You can also bring in changes one at a time with git cherry-pick. Again, check the Pro Git book for much more information about all of these operations.

Note that this will save your arctic branch locally, under the .git directory. You can back this up as you would any other important files you have.

Useful Git Commands

Command	Description
git add <_FileName_>	Add a file to the repository staging area
git branch	List all local branches (the asterisk denotes the current branch)
git branch -a	List all local and remote branches
git branch -d <_BranchName_>	Delete a local branch
git branch -D <_BranchName_>	Delete a local branch forcefully
git branch -m <_OldName_> <_NewName_>	Rename a local branch
git checkout -b <_BranchName_>	Create a new local branch and switch to it
git checkout <_BranchName_>	Switch to an existing local or remote branch
git clone <_RepositoryURL_>	Clone a public repository
git commit -am "<_Message_>"	Commit changes to all files
git commit -am "<_Message_>" -m "<_MessageURL_>"	Commit changes to all files with two message lines
git commit --amend -m "<_NewMessage_>"	Amend previous commit message
git diff	Show all changes between HEAD and working branch
git diff <_FileName_>	Show changes for a specific file between HEAD and working branch
git difftool -d <_BranchName1_> <_BranchName2_>	Compare the difference between two branches with `KDIFF3`
git fetch	Retrieve new work done by other people
git log	View repository changes
git log --oneline	Show the list of commits in one-line format
git log --summary	View repository detailed changes
git merge --no-ff --no-commit <_BranchName_>	Merge a branch into the active branch
git pull	Update local repository or branch to the newest origin commit
git push origin --delete <_BranchName_>	Delete a remote branch
git push -u origin <_BranchName_>	Push changes to the remote repository (and remember the branch)
git reset --hard HEAD~1	Undo last commit
git revert <_CommitID_>	Revert commit changes
git status	Check/display changes to the repository or particular branch
git tag	List all tags

Complicated Commands

If a branch is renamed in a repository on GitHub, the local clone on a computer needs to updated:

git branch -m OldName NewName
git fetch origin
git branch -u origin/NewName NewName
git remote set-head origin -a

How to merge changes in the feature/name1 branch into the feature/name2 branch:

git checkout feature/name1
git pull

git checkout feature/name2
git pull
git merge --no-ff --no-commit feature/name1
git commit -am "Merging feature/name1 into feature/name2" -m "MessageURL"
git difftool -d feature/name1 feature/name2
git push -u origin feature/name2