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 ROMS/TOMS files are stored on www.myroms.org/svn in a repository named src. Users can check out the most recent version 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.

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 like ​eSVN, ​RapidSVN, ​TortoiseSVN, etc.
• Each change to the repository the revision number to be incremented by 1.
  • If file_a is changed and commited, 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 tagged and latest version of ROMS/TOMS Framework:

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

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 repository trunk (latest version), enter:

• svn checkout https://www.myroms.org/svn/src/trunk mydir

To check-out the files from the ROMS repository branches, tags, and trunk, 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. 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 access 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 sub-directories.
• 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 mydir using the second command above, you'll find branches, tags and trunk directories created in your local directory. Otherwise, if you only checkout the trunk (first command above) the files and sub-directories below the trunk will be created only.
• Trunk is the main area for development, and unless otherwise instructed, work with the code in trunk.
• Tags will contain stable frozen versions.
• 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

Proceed on to the SvnTutorial.