Introduction to Subversion (Svn)

Subversion (Svn) 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 files are stored on hosted-projects in a repository named roms_sed. Users pull the most recent version to their local machines with a Svn client, use the code, making modifications as needed, then may push their changes back (again using the client) to the repository on hosted-projects.

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.

Conceptual model

• A svn server holds one or more code repositories
• A repository consists of all versions of the program/document under development, plus info on who made changes, and when.
• A svn client may access files in the repository using Svn client software
• Each each change to the repository the revision number to be incremented by 1.
  • if file_a is changed, then file_b, then file_a, then file_c, then file_b, at the end, the repository is a revision 5.
  • the revision history of file_a has 1,3; file_b has 2,5 and file_c has 4
  • revisions in a repository are sequential, but the revision history of individual files may skip some numbers.
• The repository referred to below contains the ROMS Sediment Transport model code:

      http://svn1.hosted-projects.com/cmgsoft/roms_sed
  

Using Subversion

To enable use of subversion, client software must be installed on the local machine. Most Linuxes come with subversion (the command name is svn), so shell commands may be used without installing additional software. The general form of subversion commands is:

• svn action from to {optional_qualifiers}

To check-out the files from the ROMS_SED repository, enter:

• svn checkout http://svn1.hosted-projects.com/cmgsoft/roms_sed /home/mydir/code/roms_sed

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. So to commit your changes back to the repository, cd into a local dir under subversion control (/home/mydir/code/roms_sed or below) and enter: svn commit. For more detail on command line use and syntax, see the ​Svn book.

Several GUI front-ends to subversion exist, allowing the user can have visual prompts to help them manage their files. Two free GUI clients we've tried are described in the links below:

Help on using TortoiseSVN, a GUI (subversion) client for PC

Help on using SmartSVN a java based multi-platform GUI (subversion) client

---

Important Subversion Terms

• Checkout = download a NEW project from the repository (do this once)
• Update = get the most recent changes to a project from the repository (only possible after intial checkout)
• Commit = send your changes to the project repository

Access

• Anyone should be able to view the contents of the repository, look at this wiki and view the tickets.
• A username and password are required to put your changes back into the repository.
• To work with data from a repository, you "checkout" a version.
• You can check out the most recent version or a specific release, and either the entire repository, or just certain subdirectories.
• Checking a project out makes a copy of the most recent version on the client requesting checkout
• Svn suggests only checking out into an empty directory

What you get

• If you choose to checkout the project into my_roms_sed, you’ll find trunk, branches, and tags directories created in your local directory.
• Trunk is the main area for development, and unless otherwise instructed, work with the code in trunk
• Tags will contain stable versions if they exist
• Branches will have offshoots implementing new functionality- develop in the branch, then merge back into the trunk

Work flow

• Start each session with update:
• Modify and debug the code locally
• When you’re done with changes, commit changes to the repository
• This will cause the version number to be updated at the repository
• repeat

Conflict resolution

• Svn uses copy, modify, merge as it’s operational model
• It is possible for two people to change the same chunk of code at similar times, and when the commit happens, this will be detected, and the users will have to interact to resolve the conflicts
• A process similar to diff finds the conflicts
• Right click TortoiseSvn, and try merge and/or blame to deal with conflicts

Create an SVN Branch

Only an administrator can create a branch. Send an email to: etwomey@… stating that you would like to be added to the roms_sed trac user group. Please include contact information and perferred username. If you are already registered for ROMS, please inlcude your ROMS username. Your SVN and ROMS usernames are to be the same to avoid confusion.

Check to Make Sure You Can See the Repository

You will need to know your username and password...you should have gotten an e-mail from hosted-projects. Right-click and choose Repo-browser from TortoiseSVN.
Enter the URL​https://svn1.hosted-projects.com/cmgsoft/roms_sed/
Now you should be able to look at the trunk and maybe some branches (depending on ACL), but bubba_branch won't be there yet. (You can also navigate the repository with a browser, but cannot do any of the version control stuff that follows).

Import a Copy of the Trunk

This process brings a copy of main code from the repository to your computer and places it under SVN control.
Make a directory...name it something meaningful to you, for example bubba_roms_sed
Right-click on the directory folder icon, and choose SVN Checkout...
URL of repository:
https://svn1.hosted-projects.com/cmgsoft/roms_sed/trunk
Checkout directory:
bubba_roms_sed
You should see a bunch of stuff stream by like:

Added: D:\crs\proj\Adriatic\bubba_roms_sed\ROMS  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\ROMS\Tangent  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\ROMS\Tangent\tl_rho_eos.F  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\ROMS\Tangent\tl_uv3dmix.F  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\ROMS\Tangent\tl_def_his.F  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\ROMS\Tangent\tl_step2d.F  
...
Added: D:\crs\proj\Adriatic\bubba_roms_sed\Compilers\CYGWIN-g95.mk  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\Compilers\OSF1-f90.mk  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\Compilers\Darwin-ifort.mk  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\Compilers\AIX-xlf.mk  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\Compilers\SunOS-f95.mk  
Added: D:\crs\proj\Adriatic\bubba_roms_sed\makefile  
Completed: At revision: 243  

Click OK.

Create a Branch

In TortoiseSVN, choose Branch/tag. (To see this option in TortoiseSVN, you have to right-click on a directory that is under SVN control...but it does not have to be related to the project at hand).
From WC at URL:
https://svn1.hosted-projects.com/cmgsoft/roms_sed/trunk
to URL:
https://svn1.hosted-projects.com/cmgsoft/roms_sed/branches/bubba_branch
Click OK.
(stuff streams by...)

The branch will exist in the repository...you can repeat the steps above to make a copy of the branch on your computer (but not in the same directory you made in the example above, because that contains a version of the trunk under SVN control).

Make Changes in Your Branch

You can make new files, change existing files, etc. Only existing files will automatically be under SVN control. To add new files, create them in a directory under SVN control (or copy them in from somewhere else).
Then you can right-click on the filename, and choose Add... under TortoiseSVN, or...
You will be given an opportunity later (see next step).
If you compile the code and generate a bunch of .f90 and .o files, or run the model and generate output, they will not be under SVN control unless you add them explicitly. That is usually what you want. (Storing output files here is probably a bad idea, because 1) they tend to be big and take a long time to tranfer to the repository 2) they are binary, so the tools used to compare them will not be useful, and 3) we don't have enough storage space at the repository.)

Commit Your Changes

Navigate to the top directory in your local copy of your branch, e.g., ../bubba_roms_sed and right-click. Choose SVN Commit...
Commit to: https://svn1.hosted-projects.com/cmgsoft/roms_sed/branches/bubba_branch
Message: (add a meaningful comment here)
Changes made: (Will show files with changes)
If the Show unversioned files box is checked, you will see any files you added to the directory. This is your opportunity place them under SVN control. Say you made one named foo that you want to add...check it and
Click OK.

Adding: bubba_roms_sed\foo  
Sending content: bubba_roms_sed\foo  
Completed: At revision: 244  

Work Cycle

You can Import this branch to another computer...that is the best way to synchronize, say, a desktop at work with a travelling laptop.
After that, the cycle is:
At the top local directory, right-click, and under TortoiseSVN Check for modifications. Click Check Repository.
Make changes.
Check for modifications or SVN Update (again..can't hurt).
Finally, SVN Commit...

Notes

• Everything happens at the folder level- Svn doesn’t operate on single files.
• Use svn tools to copy files into or our of a svn directory so the change can be tracked- the change will propagate to the repository on the next commit
• The .svn directory in each project main directory keeps track of the repository information, so you don’t have to say where to put commits, it puts them where it got them.

return to the roms_sed start page