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 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.
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:
name = GivenName MiddleName FamilyName
email = your@email
helper = cache --timeout=7200
helper = store --file ~/.my-credentials
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.
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:
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:
!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:
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.
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
|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|
If a branch is renamed in a repository on GitHub, the local clone on a computer needs to updated:
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/name2
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