Subversion: Difference between revisions

Latest revision as of 17:09, 8 December 2023

Subversion

ROMS source code is distributed using Subversion(SVN). There are SVN clients available for nearly every operating system and a list of popular clients can be found here. If you wish to use Subversion to maintain your own copy of ROMS you will also need an svn server. This page will help you get started with downloading ROMS with Subversion. There is also a way to download ROMS using git, described elsewhere.

WARNING: The updating of ROMS svn repositories will be discontinued on January 1, 2025

ROMS will be exclusively distributed from its GitHub repository at https://github.com/myroms. Updating the SVN repositories at https://www.myroms.org will be discontinued but kept for historical reasons.

SVN Overview

Subversion is a tool for managing software development that keeps track of who modified what and allows the return to a previous version if changes don't work as expected. All the ROMS/TOMS files are stored in a SVN repository on www.myroms.org with access controlled by requiring authentication with the same ROMS Username/Password combination assigned to registered users of the ROMS Forum.

This SVN 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 an svn client. Don't attempt to use a regular web browser to browse or download files from the SVN repository - there are much better tools for interacting with the code repository. See the notes below under the heading View the Repository.

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

Below is a general description of how subversion works. Please look at the svn book for more detailed information. Brief instructions for using two GUI clients (one for PC and one for Linux) we've tried are included.

Downloading ROMS

WARNING: It is strongly suggested that you checkout 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 Subversion repository, svn client software must be installed on your local machine. If you are compiling subversion on your own be sure to build it with SSL support or you will not be able to download the ROMS source code. Most Linux distributions come with subversion (the command name is svn), so shell commands may be used without installing additional software. If your username on your local computer is not the same as your ROMS username you will need to pass the --username <username> option to svn; an example is given below. The general form of subversion commands is:

   svn action from to {optional_qualifiers}

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

   svn checkout https://www.myroms.org/svn/src/trunk MyDir

where MyDir is the destination directory on your local computer. It will be created if not found. If your username on your local computer is not the same as your ROMS username you will need to pass the --username option to svn:

   svn checkout --username joe_roms https://www.myroms.org/svn/src/trunk MyDir

Files for test cases and other repositories

There is an additional repository that provides idealized Test Cases and realistic applications to introduce you to ROMS many capabilities. You may use these examples as a guideline in setting up your own application. Currently, this repository requires ~388MB of disk space. This is because the realistic applications require several input NetCDF files. To checkout this repository, enter:

   svn checkout https://www.myroms.org/svn/src/test MyTest

Similarly, to check-out the files from the ROMS repository matlab (official scripts), enter:

   svn checkout https://www.myroms.org/svn/src/matlab MyDir

To check-out the files from the ROMS repository plot (NCAR's library-based plotting package), enter:

   svn checkout https://www.myroms.org/svn/src/plot MyDir

To check-out the files from the ROMS repository branches, plot, matlab, tags, test, and trunk, (this is not recommended because it takes a long time to complete) enter:

   svn checkout https://www.myroms.org/svn/src MyDir

You only check out once, after that, a hidden directory called .svn exists to keep track of the source, destination and a bunch of other information. Your username and password will also be saved. For more detail on command line use and syntax, see the svn book.

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

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:

   svn update

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

Code changes

As you use ROMS, you may find yourself adding new files and new chunks of code to existing files. Unless you are a developer with write access to the repository at www.myroms.org, you have no easy way to save your changes within the svn framework, since any one directory can only point to one repository. To keep getting updates from the trunk, you must keep using the svn server at myroms.org. At the very least, saving a tarball before fetching major updates is a prudent step. A more organized approach to revision control for your own files can be achieved by using git.

Conflicts

Sometimes when you make changes to your copy of the ROMS code, those changes will conflict with changes made to the repository (the code that resides at https://www.myroms.org/svn/src/trunk). This means that the changes from the server overlapped with your own, and now you have to manually choose between them.

Whenever a conflict occurs, three things typically occur to assist you in resolving that conflict:

Subversion halts during the update, offering you several choices, and remembers that the file is in a state of conflict if you don't clear it right then.
If Subversion considers the file to be mergeable, it places conflict markers (special strings of text which delimit the “sides” of the conflict, usually "<" and ">" characters) into the file to visibly demonstrate the overlapping areas.
For every conflicted file, Subversion places three extra unversioned (not under Subversion control) files in your working copy:

filename.mine: This is your file as it existed in your working copy (local copy) before you updated your working copy. This file has only your latest changes in it. (If Subversion considers the file to be unmergeable, then the .mine file isn't created, since it would be identical to the working file.)
filename.rOLDREV: This is the file that was the BASE revision before you updated your working copy. That is, the file that you checked out before you made your latest edits.
filename.rNEWREV: This is the file that your Subversion client just received from the server when you updated your working copy. This file corresponds to the HEAD (latest) revision of the repository.

For example, let's say you checked out revision 280 and made some changes to User/Functionals/ana_hmixcoef.h. Now you want to update your ROMS source code to take advantage of a new algorithm but when you run svn update your ana_hmixcoef.h is now in conflict with the new version in the repository.

> svn update
U Version
U ROMS/Modules/mod_mixing.F
U ROMS/Functionals/ana_hmixcoef.h
C User/Functionals/ana_hmixcoef.h
Updated to revision 291.

>

The above is with an older version of svn. The latest, greatest does this:

Conflict discovered in 'ROMS/Utility/inp_par.F'.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options:

Selecting (p) will behave as the old version.

If you get a conflict, you need to do one of three things:

Merge the conflicted text “by hand” by examining and editing the conflict markers within the file.
Copy one of the temporary files on top of your working file.
Run svn revert <filename> to throw away all of your local changes.

Once you've resolved the conflict, you need to let Subversion know by running svn resolved. This removes the three temporary files and Subversion no longer considers the file to be in a state of conflict. More on this below.

Merging Conflicts by Hand

Note: We recommend that you make a backup of the <filename>.mine file before you begin to be certain you don't accidentally lose your modifications.

To merge your changes with those from the latest revision in the repository, open User/Functionals/ana_hmixcoef.h in your favorite editor and look for a string of "<" characters. You should see something like this:

<<<<<<< .mine
#ifndef DISTRIBUTE
IF (Lanafile.and.(tile.eq.0)) THEN
#else
IF (Lanafile) THEN
#endif
=======
#ifdef DISTRIBUTE
IF (Lanafile) THEN
#else
IF (Lanafile.and.(tile.eq.0)) THEN
#endif
>>>>>>> .r291

After comparing the two code blocks (separated by the "=" symbol), you decide that you prefer the logic from the repository so you remove the conflict markers and your code so the section now looks like this:

#ifdef DISTRIBUTE
IF (Lanafile) THEN
#else
IF (Lanafile.and.(tile.eq.0)) THEN
#endif

Now you can save the file and let Subversion know that you have resolved the conflict:

> svn resolved User/Functionals/ana_hmixcoef.h
Resolved conflicted state of 'User/Functionals/ana_hmixcoef.h'

Copying a File Onto Your Working File

Note: We recommend that you make a backup of the <filename>.mine file before you begin to be certain you don't accidentally lose your modifications.

If you get a conflict and decide that you want to throw out your changes, you can merely copy one of the temporary files created by Subversion over the file in your working copy. Let's say you want to use the new revision from the repository:

> cd User/Functionals
> ls ana_hmixcoef.h*
ana_hmixcoef.h ana_hmixcoef.h.mine ana_hmixcoef.h.r280 ana_hmixcoef.h.r291

> cp ana_hmixcoef.h.r291 ana_hmixcoef.h
> svn resolved ana_hmixcoef.h
Resolved conflicted state of 'ana_hmixcoef.h'

Punting: Using svn revert

Note: We recommend that you make a backup of the <filename>.mine file before you begin to be certain you don't accidentally lose your modifications.

If you get a conflict, and upon examination decide that you want to throw out your changes and start your edits again, just revert your changes:

> cd User/Functionals
> svn revert ana_hmixcoef.h
Reverted 'ana_hmixcoef.h'

Note that when you revert a conflicted file, you don't have to run svn resolved.

Using GUI SVN Clients

WARNING: It is strongly suggested that you checkout 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.

Most of the GUI svn clients are very similar to each other. In this example we will use eSVN, although several users have reported better luck with the free "Foundation Version" of SmartSVN.

View the Repository

The easiest way to view a repository is to simply look at it with Trac in a web browser. Enter the URL:

https://www.myroms.org/projects/src/browser

You will be prompted for your ROMS username and password. This is also a good way to see individual files in the repository without actually downloading them.

To view the repository with eSVN, Click on the file menu and choose "Browse Repository" and enter repository URL:

Click "Browse" and you should be able to look at the branches, tags, and trunk. You can navigate the repository with a web browser as described above, but cannot do any of the version control stuff that follows.

Checkout a Copy of the Trunk

This process brings a copy of the main code from the repository to your computer and places it under svn control. "Local Path" tells eSVN where you would like your copy of the source code to be located.

You should see a bunch of text stream by like:

   svn checkout https://www.myroms.org/svn/src/trunk /home/ocean/src --username ocean 
   --password ****** --non-interactive 
   A /home/ocean/src/ROMS
   A /home/ocean/src/ROMS/License_ROMS.txt
   A /home/ocean/src/ROMS/Tangent
   A /home/ocean/src/ROMS/Tangent/tl_rho_eos.F
   A /home/ocean/src/ROMS/Tangent/tl_uv3dmix.F
   A /home/ocean/src/ROMS/Tangent/tl_def_his.F
   ...
   A /home/ocean/src/Compilers/UNICOS-mk-f90.mk
   A /home/ocean/src/Compilers/CYGWIN-g95.mk
   A /home/ocean/src/Compilers/OSF1-f90.mk
   A /home/ocean/src/Compilers/Darwin-ifort.mk
   A /home/ocean/src/Compilers/AIX-xlf.mk
   A /home/ocean/src/Compilers/SunOS-f95.mk
   A /home/ocean/src/makefile
   Checked out revision 11.
   successfully (0)

@@ Line 1: / Line 1: @@
 <div class="title">Subversion</div>
-ROMS source code is distributed using [http://subversion.tigris.org Subversion](SVN). There are SVN clients available for nearly every operating system and a list of popular clients can be found [http://subversion.tigris.org/links.html#clients here]. If you wish to use Subversion to maintain your own copy of ROMS you will also need an [http://subversion.tigris.org/project_packages.html svn server]. This page will help you get started with downloading ROMS with Subversion.
+ROMS source code is distributed using [http://subversion.tigris.org Subversion](SVN). There are SVN clients available for nearly every operating system and a list of popular clients can be found [http://subversion.tigris.org/links.html#clients here]. If you wish to use Subversion to maintain your own copy of ROMS you will also need an [http://subversion.tigris.org/project_packages.html svn server]. This page will help you get started with downloading ROMS with Subversion. There is also a way to download ROMS using git, described [[ROMS_git | elsewhere]].
+===<span class="red">WARNING:</span> <span class="blue">The updating of ROMS svn repositories will be discontinued on</span><span class="red"> January 1, 2025</span>===
+'''ROMS''' will be exclusively distributed from its '''GitHub''' repository at [https://github.com/myroms https://github.com/myroms]. Updating the '''SVN''' repositories at [https://www.myroms.org https://www.myroms.org] will be discontinued but kept for historical reasons.
 ==SVN Overview==
-Subversion is a tool for managing software development that keeps track of who modified what and allows returning to a previous version if changes don't do what was expected. All the ROMS/TOMS files are stored in a repository '''https://www.myroms.org/svn/src''' (note that this link requires the secure '''https''' URI).  Authentication is with the same ROMS Username/Password combination assigned to registered users of the ROMS Forum.
+Subversion is a tool for managing software development that keeps track of who modified what and allows the return to a previous version if changes don't work as expected. All the ROMS/TOMS files are stored in a SVN repository on '''www.myroms.org''' with access controlled by requiring authentication with the same ROMS Username/Password combination assigned to registered users of the ROMS Forum.
+This SVN 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 an '''svn client'''.  Don't attempt to use a regular web browser to browse or download files from the SVN repository - there are much better tools for interacting with the code repository. See the notes below under the heading '''View the Repository'''.
-Users can browse release versions under ''tags'', or the current ''trunk'' of code in development. Users can check out the recent versions (''tags'' or ''trunk'') to their local machines with a '''svn client'''. Since this is the official version of the code, only the developers are allowed to change this repository. However, users can have their own repository on their local computer.
+We strongly recommend users always check out the current ''trunk'' version since this has the most recent updates and bug fixes. The ''tags'' version is kept largely as an historical record of stable releases at the conclusion of major code upgrades.
 Below is a general description of how subversion works. Please look at the [http://svnbook.red-bean.com/ svn book] for more detailed information. Brief instructions for using two GUI clients (one for PC and one for Linux) we've tried are included.
-==Using Subversion==
+==Downloading ROMS==
-In order download source code from a Subversion repository, '''svn client''' software must be installed on your local machine. If you are compiling subversion on your own be sure to build it with '''SSL support''' or you will not be able to download the ROMS source code. Most Linux distributions come with subversion (the command name is '''svn'''), so shell commands may be used without installing additional software. If your username on your local computer is not the same as your ROMS username you will need to pass the ''''--username <username>'''' option to '''svn'''; an example is given below. The general form of subversion commands is:
+{{warning}}'''WARNING:''' It is strongly suggested that you checkout 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 <span class="red">dos2unix</span> or <span class="red">recode</span>. Even with these utilities you may still have problems compiling ROMS.
+In order download source code from a Subversion repository, '''svn client''' software must be installed on your local machine. If you are compiling subversion on your own be sure to build it with '''SSL support''' or you will not be able to download the ROMS source code. Most Linux distributions come with subversion (the command name is '''svn'''), so shell commands may be used without installing additional software. If your username on your local computer is not the same as your ROMS username you will need to pass the '''--username <username>''' option to '''svn'''; an example is given below. The general form of subversion commands is:
      <span class="red">svn</span> action from to {optional_qualifiers}
@@ Line 22: / Line 32: @@
      <span class="red">svn checkout --username joe_roms <nowiki>https://www.myroms.org/svn/src/trunk</nowiki> MyDir</span>
-To check-out the files from the ROMS repository '''branches''', '''tags''', and '''trunk''', (this is not recomended because it takes a long time to complete) enter:
+===Files for test cases and other repositories===
+There is an additional repository that provides idealized [[Test Cases]] and realistic applications to introduce you to ROMS many capabilities. You may use these examples as a guideline in setting up your own application. Currently, this repository requires '''~388MB''' of disk space. This is because the realistic applications require several input NetCDF files. To checkout this repository, enter:
+    <span class="red">svn checkout <nowiki>https://www.myroms.org/svn/src/test</nowiki> MyTest</span>
+Similarly, to check-out the files from the ROMS repository '''matlab''' (official scripts), enter:
+    <span class="red">svn checkout <nowiki>https://www.myroms.org/svn/src/matlab</nowiki> MyDir</span>
+To check-out the files from the ROMS repository '''plot''' (NCAR's library-based plotting package), enter:
+    <span class="red">svn checkout <nowiki>https://www.myroms.org/svn/src/plot</nowiki> MyDir</span>
+To check-out the files from the ROMS repository '''branches''', '''plot''', '''matlab''', '''tags''', '''test''', and '''trunk''', (this is not recommended because it takes a long time to complete) enter:
      <span class="red">svn checkout <nowiki>https://www.myroms.org/svn/src</nowiki> MyDir</span>
@@ Line 29: / Line 52: @@
 Several GUI front-ends to subversion exist, allowing the user to have visual prompts to help them manage their files.
+===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:
+    <span class="red">svn update</span>
+Subversion 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.
+===Code changes===
+As you use ROMS, you may find yourself adding new files and new chunks of code to existing files. Unless you are a developer with write access to the repository at www.myroms.org, you have no easy way to save your changes within the svn framework, since any one directory can only point to one repository. To keep getting updates from the trunk, you must keep using the svn server at myroms.org. At the very least, saving a tarball before fetching major updates is a prudent step. A more organized approach to revision control for your own files can be achieved by using [http://git-scm.com/ git].
+===Conflicts===
+Sometimes when you make changes to your copy of the ROMS code, those changes will conflict with changes made to the repository (the code that resides at <span class="forestGreen"><nowiki>https://www.myroms.org/svn/src/trunk</nowiki></span>). This means that the changes from the server overlapped with your own, and now you have to manually choose between them.
+Whenever a conflict occurs, three things typically occur to assist you in resolving that conflict:
+:*Subversion halts during the update, offering you several choices, and remembers that the file is in a state of conflict if you don't clear it right then.
+:*If Subversion considers the file to be mergeable, it places conflict markers (special strings of text which delimit the “sides” of the conflict, usually "<" and ">" characters) into the file to visibly demonstrate the overlapping areas.
+:*For every conflicted file, Subversion places three extra unversioned (not under Subversion control) files in your working copy:
+::*'''filename.mine:''' This is your file as it existed in your working copy (local copy) before you updated your working copy. This file has only your latest changes in it. (If Subversion considers the file to be unmergeable, then the .mine file isn't created, since it would be identical to the working file.)
+::*'''filename.rOLDREV:''' This is the file that was the '''BASE''' revision before you updated your working copy. That is, the file that you checked out before you made your latest edits.
+::*'''filename.rNEWREV:''' This is the file that your Subversion client just received from the server when you updated your working copy. This file corresponds to the HEAD (latest) revision of the repository.
+For example, let's say you checked out revision 280 and made some changes to <span class="forestGreen">User/Functionals/ana_hmixcoef.h</span>. Now you want to update your ROMS source code to take advantage of a new algorithm but when you run <span class="red">svn update</span> your <span class="forestGreen">ana_hmixcoef.h</span> is now in conflict with the new version in the repository.
+:<div class="box">&gt; <span class="red">svn update</span><br>U Version<br>U ROMS/Modules/mod_mixing.F<br>U ROMS/Functionals/ana_hmixcoef.h<br>C User/Functionals/ana_hmixcoef.h<br>Updated to revision 291.<br><br>&gt;</div>
+The above is with an older version of svn. The latest, greatest does this:
+:<div class="box">Conflict discovered in 'ROMS/Utility/inp_par.F'.<br>Select: (p) postpone, (df) diff-full, (e) edit,<br>        (mc) mine-conflict, (tc) theirs-conflict,<br>        (s) show all options:</div>
+Selecting (p) will behave as the old version.
+If you get a conflict, you need to do one of three things:
+:*Merge the conflicted text “by hand” by examining and editing the conflict markers within the file.
+:*Copy one of the temporary files on top of your working file.
+:*Run <span class="red">svn revert <filename></span> to throw away all of your local changes.
+Once you've resolved the conflict, you need to let Subversion know by running <span class="red">svn resolved</span>. This removes the three temporary files and Subversion no longer considers the file to be in a state of conflict. More on this below.
+====Merging Conflicts by Hand====
+{{note}}'''Note:''' We recommend that you make a backup of the '''<filename>.mine''' file before you begin to be certain you don't accidentally lose your modifications.
+To merge your changes with those from the latest revision in the repository, open <span class="forestGreen">User/Functionals/ana_hmixcoef.h</span> in your favorite editor and look for a string of "<" characters. You should see something like this:
+:<div class="box">&lt;&lt;&lt;&lt;&lt;&lt;&lt; .mine<br>#ifndef DISTRIBUTE<br>      IF (Lanafile.and.(tile.eq.0)) THEN<br>#else<br>      IF (Lanafile) THEN<br>#endif<br>=======<br>#ifdef DISTRIBUTE<br>      IF (Lanafile) THEN<br>#else<br>      IF (Lanafile.and.(tile.eq.0)) THEN<br>#endif<br>&gt;&gt;&gt;&gt;&gt;&gt;&gt; .r291</div>
+After comparing the two code blocks (separated by the "=" symbol), you decide that you prefer the logic from the repository so you remove the conflict markers and your code so the section now looks like this:
+:<div class="box">#ifdef DISTRIBUTE<br>      IF (Lanafile) THEN<br>#else<br>      IF (Lanafile.and.(tile.eq.0)) THEN<br>#endif</div>
+Now you can save the file and let Subversion know that you have resolved the conflict:
+:<div class="box">&gt; <span class="red">svn resolved User/Functionals/ana_hmixcoef.h</span><br>Resolved conflicted state of 'User/Functionals/ana_hmixcoef.h'</div>
+====Copying a File Onto Your Working File====
+{{note}}'''Note:''' We recommend that you make a backup of the '''<filename>.mine''' file before you begin to be certain you don't accidentally lose your modifications.
+If you get a conflict and decide that you want to throw out your changes, you can merely copy one of the temporary files created by Subversion over the file in your working copy. Let's say you want to use the new revision from the repository:
+:<div class="box">&gt; <span class="red">cd User/Functionals</span><br>&gt; <span class="red">ls ana_hmixcoef.h*</span><br>ana_hmixcoef.h  ana_hmixcoef.h.mine  ana_hmixcoef.h.r280  ana_hmixcoef.h.r291<br><br>&gt; <span class="red">cp ana_hmixcoef.h.r291 ana_hmixcoef.h</span><br>&gt; <span class="red">svn resolved ana_hmixcoef.h</span><br>Resolved conflicted state of 'ana_hmixcoef.h'</div>
+====Punting: Using <span class="red">svn revert</span>====
+{{note}}'''Note:''' We recommend that you make a backup of the '''<filename>.mine''' file before you begin to be certain you don't accidentally lose your modifications.
+If you get a conflict, and upon examination decide that you want to throw out your changes and start your edits again, just revert your changes:
+:<div class="box">&gt; <span class="red">cd User/Functionals</span><br>&gt; <span class="red">svn revert ana_hmixcoef.h</span><br>Reverted 'ana_hmixcoef.h'</div>
+Note that when you revert a conflicted file, you don't have to run <span class="red">svn resolved</span>.
 ==Using GUI SVN Clients==
-Most of the GUI '''svn clients''' are very similar to each other. In this example we will use eSVN.
+{{warning}}'''WARNING:''' It is strongly suggested that you checkout 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 <span class="red">dos2unix</span> or <span class="red">recode</span>. Even with these utilities you may still have problems compiling ROMS.
+Most of the GUI '''svn clients''' are very similar to each other. In this example we will use eSVN, although several users have reported better luck with the free "Foundation Version" of [http://www.syntevo.com/smartsvn/index.jsp/ SmartSVN].
 ===View the Repository===

Subversion: Difference between revisions

Latest revision as of 17:09, 8 December 2023

Contents

WARNING: The updating of ROMS svn repositories will be discontinued on January 1, 2025

SVN Overview

Downloading ROMS

Files for test cases and other repositories

Updates

Code changes

Conflicts

Merging Conflicts by Hand

Copying a File Onto Your Working File

Punting: Using svn revert

Using GUI SVN Clients

View the Repository

Checkout a Copy of the Trunk

Navigation menu

Page actions

Page actions

Personal tools

Navigation

Search

Help

Tools