Using local Subversion Repository (SVN)

How to view and use SVN projects

• Each project is stored in its own Subversion (SVN) repository. SVN is a version-control system that keeps track of changes in a project over time. At UCSF The /raid4/svn/ directory contains all of the local SVN repositories. Each repository stores the code for a single project or utility. You can see the names of the existing repositories by typing:

ls /raid4/svn

At UofT, svn is located at the following path:

/mnt/nfs/software/svn/

For example:

[prompt]$ ls /raid4/svn
dock6  rocutil

• To view the contents of a particular repository, you can use svnlook:

[prompt]$ svnlook tree /raid4/svn/rocutil/
/
 trunk/
  python/
   rocutil.py
  c/
   roc2py.c
   roc.c
   setup.py
   roc.h
  README
 branches/
 tags/

• Use the svn checkout command to make a copy of the current code from the repository's main trunk. The trunk is usually the current version of the code, whereas the branches directory contains code still in development. Finally, the tags directory may contain specific versions of the project (like "1.0" or "1.1" etc). Not all projects necessarily have branch and tag code.

[prompt]$ svn checkout file:///raid4/svn/rocutil
A    rocutil/trunk
A    rocutil/trunk/python
A    rocutil/trunk/python/rocutil.py
A    rocutil/trunk/c
A    rocutil/trunk/c/roc2py.c
A    rocutil/trunk/c/roc.c
A    rocutil/trunk/c/setup.py
A    rocutil/trunk/c/roc.h
A    rocutil/trunk/README
A    rocutil/branches
A    rocutil/tags
Checked out revision 1.

Now you can use the code that has been copied to your own rocutil/ directory.

• If you make changes to the code and want to save them to the repository, use the svn commit command. When you commit, you always have to include a short message explaining what has changed:

[prompt]$ svn commit rocutil -m "rewrote code to include dancing dinosaurs"

How to create a new project repository

In order to build your own repository for a project, you need to first create the repository and then import the existing code into it.

• Create a repository in /raid4/svn/ using the svnadmin create command as follows:

[prompt]$ svnadmin create /raid4/svn/rubberducky

In this example, the new repository's name is rubberducky. Note also that the svnadmin command (and the svnlook command from above) both use a filesystem path (eg, /raid4/...) instead of a URL (eg, file:///raid4/...).

• Now that the repository is created, use svn import to add your existing code. For example, if you have code in a folder called ~/mycode/, run the following command:

[prompt]$ svn import ~/mycode file:///raid4/svn/rubberducky -m "initial import"

The rubberducky project is now ready to use.

• IMPORTANT NOTE: By default, only you can make changes to a project that you create. If you want other people in the lab to be able to contribute to the project also (eg, allow them to commit changes), you need to change the directory's write permissions like this:

[prompt]$ chmod g+w /raid4/svn/rubberducky -R

Where rubberducky is the name of your project.

How to add/delete files to/from an existing project

The svn commit command commits changes you have made to all files in the project. But SVN requires an explicit command to add new files to the project, or to delete old ones from it.

• Adding a file: Create the new file in your project as desired. Once you're ready to add it, type:

[prompt]$ svn add happiness.key

Where happiness.key is the name of the new file. The file will now be added on your next svn commit.

• Deleting a file:

[prompt]$ svn del velociraptor.hlp

Where velociraptor.hlp is the name of the file to be deleted. The file will now be deleted on your next svn commit.

What are trunks, branches, and tags?

As you continue develop your code, you may wish to work on side branches without immediately affecting the main project, or you may wish to tag a certain version (e.g., 'release-1.0') so you can easily come back to it later. SVN handles these situations by creating a subdirectory in each case, using the svn copy command.

Note that the trunk, branches, and tags arrangement is simply an organizational convention, which you can also choose not to follow.

• Trunk. The trunk is the main development branch of your code. You may have noticed that the rocutil project examples above placed all of the code in a trunk directory. To create the trunk, simply place your code in a directory called trunk before you originally create your SVN repository. If you've already created a repository without one (such as the rubberducky example above) but want to add it now, here is an example of how to do that:

[prompt]$ svn mkdir trunk
[prompt]$ svn move happiness.key trunk
...
[prompt]$ svn commit -m "now i have a trunk!"

• Branches. The branches directory is where you put versions of the code that you're working on but don't want to be the main development tree. They may be unstable code, or a side-project. You can choose later to merge this branch back into the main tree, once it's ready (see link at end of this section). You create branches simply by creating a branches subdirectory, and then using svn copy to put the starting code into it:

[prompt]$ svn mkdir branches
[prompt]$ svn copy trunk/* branches/rubberchicken
[prompt]$ svn commit -m "the rubberchicken lives"

• Tags. The tag directory is typically where you store your releases. A tag is a snapshot of the code at a particular point. The procedure to create a tag is -- surprise, surprise -- nearly identical to that of creating a branch (you just don't plan to modify the tag's contents later):

[prompt]$ svn mkdir tags
[prompt]$ svn copy trunk/* tags/release-1.0
[prompt]$ svn commit -m "rubberducky is go for launch"

Note SVN implements "cheap copies" -- using UNIX hardlinks, no extra data is stored for each copy beyond the actual changes. This means that tags and branches do not use up significantly more disk space than the single trunk alone, even for large projects.

For more information on SVN branches and merging, see Chapter 4, Official SVN tutorial

How to get more SVN help

A quick way to list all of the commands and get help on them is:

[prompt]$ svn help

For a more comprehensive tutorial, see the Official SVN tutorial