Subversion Documentation

The Subversion Client

To execute Subversion commands you must be on a workstation or server that has the Subversion client software installed. The Subversion client is installed on webtest.ucar.edu which is available for ssh login to anyone who already has an account on webpub.ucar.edu. Alternatively, you can install the Subversion client on your own workstation. Downloads for the Subversion client software are available for Mac OS X, UNIX and Windows. A GUI client comparison is also available if you prefer a GUI to the command line.

Subversion Commands Quick Start

If you are already familiar with CVS, some Subversion examples might be all that you need to get started. More detailed instructions and examples can be found further down the page.

Example: Add a file

In this example, we list the codebase, checkout, add a file and commit the change back to the repository.

   svn list http://subversion.ucar.edu/test/Project


   svn checkout http://subversion.ucar.edu/test/Project
			
   cd Project
		
   touch filename
			
   svn add filename
			
   svn commit

Other useful commands

   svn help
   svn help <subcommand>

Available subcommands (with abbreviations)
   add
   blame (praise, annotate, ann)
   cat
   checkout (co)
   cleanup
   commit (ci)
   copy (cp)
   delete (del, remove, rm)
   diff (di)
   export
   help (?, h)
   import
   info
   list (ls)
   lock
   log
   merge
   mkdir
   move (mv, rename, ren)
   propdel (pdel, pd)
   propedit (pedit, pe)
   propget (pget, pg)
   proplist (plist, pl)
   propset (pset, ps)
   resolved
   revert
   status (stat, st)
   switch (sw)
   unlock
   update (up)

Key Subversion Concepts

The repository is where files are stored under Subversion on the server.

The contents of a project in the repository are usually copied into a local directory. This is known as the working directory, and is separate from the repository.

The operation of copying the project to the local directory is called "check out" and the reverse is "check in".

The connection to a Subversion repository is usually given as a URL, for example: http://subversion.ucar.edu/

Authentication is how you prove who you are, such as through a username and password.

Authorization deals with what you have access to and the permissions on what you can do. In this context, authorization is about your file read and write permissions.

Conventions

The WEG convention is to create a single repository for your organization which can hold multiple software projects. To use the WEG repository as an example:

http://subversion.ucar.edu/WEG/Project1http://subversion.ucar.edu/WEG/Project2

Cross-organizational projects and initiatives can be placed at the top level, such as http://subversion.ucar.edu/Project.

Authentication (Login)

The subversion.ucar.edu server uses Apache-based authentication. UCAS authentication is not available for this service since Subversion clients can be configured to store passwords locally. If you run your own Subversion client, please make sure local password storage is turned off.

Here is an example login session:

svn list http://subversion.ucar.edu/WEG

Authentication realm: WEG Subversion

Password for 'sitongia': <enter password>

Authorization (Permissions)

Your project in Subversion can be configured to authorize access in a number of simple and convenient ways. The only access methods are read and write. Your project can be configured to grant read access to the world, so that everyone can download your software. Or, you could limit access to only those people who are authenticated. Write access, similarly, can be very open or limited to a number of developers.

Authorization can be configured differently for different parts of your project. For example, you could configure anonymous read access to your project source code and documentation, but have a subdirectory of private documents that are only readable by developers. For assistance with setting permissions, submit a ticket to the CISL Help Desk.

Using Subversion

Let's assume that you are a software manager who has already requested a project repository under the WEG Subversion service and that you have a software project on your local workstation that you will put into this repository to manage. Your software is in the directory Project and you want to put it into the Subversion repository /WEG/Project so that the URL you will give to people will look like http://subversion.ucar.edu/WEG/Project.

Step 1. Organize your project

The creators of Subversion recommend that you organize the directory structure of your project so that it will be easy to create multiple revisions of it in the repository in the future. The usual convention of this is to have three directory areas, named "trunk", "tags" and "branches". Mostly, these names are from the usual tree metaphor. Your primary directory will be trunk. You needn't be concerned about the other directories right now. If you're interested in learning more about this, please see the Subversion Red Book.

After creating these three directory names in your Subversion project, the next step is to move all of your source code and document directories into the trunk directory using the import command. The other two directories will be empty. Let's say your project is in a directory named Project. Your directory layout will then look like:

Step 2. Import your project

The process of copying your software for the first time from your local directory to the repository is called importing. You will only do this once. In the future, when you make changes to your software and copy those changes from the local directory to the server, you will use a slightly different process, called commiting.

You need to be very careful about how you construct this command for your project, because you could end up with the files in the wrong part of the repository or with a directory path that you didn't intend to have.

On the local workstation, you should cd to the directory above your project. Here is the command you would use:

svn import Project http://subversion.ucar.edu/WEG/Project --message "A Short Title for My Project"

The URL used in the import command is exactly the same as what you would give to others to access the files in Subversion.

The message can be any text and should be a sensible unique short description or title for your project.

Step 3. Browse your project

Here is how you would list the contents of the repository now, to see that it has been checked in. Again, using the same URL as used before:

svn list http://subversion.ucar.edu/WEG/Project

Step 4. Check out your project

Now you will throw away your local directory and make a fresh copy of it from the repository! Your files are safe in Subversion, but you should keep a copy of the files you have right now in case the import command put your files into the wrong place. Let's say you cd into a different directory on your local workstation named "projects". You can check out your project into this new location in your local workstation.

svn checkout http://subversion.ucar.edu/WEG/Project

Now you have a fresh copy of your files in a subdirectory called Project under the directory projects. From now on, you'll keep this copy and the copy in the repository in sync by using Subversion commands.

You might be curious about how your local directory knows that it is participating in Subversion's version control. That is through the special directory you'll find hidden in your working directory, named .svn. Don't touch any of the files in that directory!

Step 5. Make changes to your project and commit them to the repository

Let's say you edit some files, add some new files, and delete some other files. Once you are done making a set of changes that are related to each other in some way, you'll probably want to copy those changes to the repository as a group so that in the future you'll have a record that those changes were made. When you've finished making those changes, you run the following command while in the project working directory Project:

svn commit

Now that the working directory is managed by Subversion, you no longer have to specify the URL (it is defined automatically because of the special .svn directory).

This command will bring up the default editor that you've specified in your workstation environment, so that you can add comments related to this operation. This is how you document why you made the group of changes and have grouped them together. (If you need help configuring your editor, please contact your computer support staff.)

Step 6. Tell others about your project URL

You can tell others about your repository by giving them the URL you have been using and telling them that Subversion is the version control system. If you have external collaborators (people who are not connected to the UCAR network), be sure to give them the proxy URL which differs in that it uses the https protocol and adds the word proxy in front of the server name.

Internal URL (for UCAR staff): http://subversion.ucar.edu/WEG/

External URL (for collaborators): https:/proxy.subversion.ucar.edu/WEG/

Subversion and CVS

The Concurrent Versions System (CVS) may be the most commonly used version control system, but Subversion is intended to be the replacement for it. There are a couple of primary approaches to converting your code control from CVS to Subversion.

The easiest approach is simply to move your latest copy of your files into Subversion. You would start from an updated local CVS working directory, ignoring the history of your project that is contained within the CVS repository. First, remove the CVS directories within your working directory tree (CVS stores information about your files in a directory named "CVS" within each subdirectory of your working directory). Then, use the procedure documented above to import your project, beginning with Step 1.

Ideally, one would convert a CVS repository to a Subversion repository with the inclusion of all the history of changes and comments that are in the CVS repository. However, this is non-trivial and too complex to relate in this document. If you would like to try this, you should start with the section in the Subversion Red Book at the bottom of page 313 ("Converting a Repository from CVS to Subversion"). That section gives references to tools which can be used to attempt this effort.

Tips

When you would like to start using the WEG Subversion service, you should first ask around your group to find out if they already have a repository that you can start using immediately. If not, then you can request a new Subversion repository in which you can check in files. Gather the information described in About the WEG Subversion service and submit a work request to the CISL Help Desk.

If you're not yet familiar with Subversion, then a good reference is the free Subversion Red Book.

Subversion is very sensitive to the syntax of the URL in commands. For example, adding a trailing slash ("/") to the URL may cause an error which leads you to believe that there are no files at that path.

In contrast with CVS, Subversion uses a global revision number for the repository. The repository that your project is in, on the server, is likely to be shared with other projects. Committing changes from any projects will increment the global revision number. So, you shouldn't be surprised if the revision number increases by a number larger than 1 when you commit. It simply means that someone else has committed between your last and current commits. The revision number has less significance in this context for Subversion than it does for CVS.