Subversion

Notes I wrote up in 2006 regarding subversion. It functions as an intro guide to subversion, both as a client and as an administrator.

I've been using subversion (nope, not a git guy yet) for most of my own work, I even got our projects at my current job onto subversion. It's much better than source safe/offsite (which I used at a previous job) and I even prefer it to CVS. Subversion is designed specifically to be a modern replacement for CVS and shares a number of the same key developers. It uses a copy-modify-merge for file sharing. To read more about subversion, you can read their very good documentation at http://svnbook.red-bean.com/. The following is a link to an appendix from the svnbook that introduces subversion for cvs users. I think that it will be a very helpful and painless way to quickly understand subversion with a cvs background. You can read it starting at http://svnbook.red-bean.com/en/1.2/svn.forcvs.html.

Subversion’s homepage is http://subversion.tigris.org/. I install it using the instructions found on http://www.excastle.com/blog/archive/2005/05/31/1048.aspx.

The most direct way of using subversion is through the subversion client tool called svn. You can download the tool from subversion’s site, http://subversion.tigris.org/. For directions on using the tool, refer to the appropriate section at http://svnbook.red-bean.com/.

Another subversion client option for Win32 users is TortoiseSVN, which is implemented as a Windows shell extension. TortoiseSVN can be downloaded from http://tortoisesvn.tigris.org/. It is very simple and intuitive to use as all commands are added to the right click context menu when using windows explorer. Special icons are used to show which files and folders are under revision control.

If you're using Eclipse, there is a plugin called SubClipse that will integrate Eclipse and Subversion. You can download the plug-in from http://subclipse.tigris.org/. A good guide to installation and usage for the plug-in can be found at http://dev2dev.bea.com/pub/a/2005/11/subclipse.html?page=1.

The goal of the following sections is to explain how to use the subversion repository I'm administering from a Windows 2000 machine, a Trusted Solaris 8 machine, and a Solaris 10 machine. Solaris instructions should be pretty similar for any UNIX and Windows 2000 should be pretty similar to any Windows in general


Brief Intro to Using Subversion as a Client

The true guide to subversion is http://svnbook.red-bean.com/. It’s somewhat long, so I’ve created a short document to help get you started using it.

The Basics

Subversion is a version control system. It is primarily a "copy-modify-merge" system as opposed to a "lock-modify-unlock" system, although it has optional features to do the latter. Subversion works on the client by using hidden ".svn" folders in the directory you checkout to that you must not remove. Subversion repositories generally have top-level folders of trunk, branches, and tags. Trunk contains the working data, branches hold code branches, and tags allow you to store named "snapshots" of the project. Subversion uses only one revision number for the entire project: anytime anything is changed, the revision number goes up. For features and general information, you can look at the wikipedia page: http://en.wikipedia.org/wiki/Subversion_%28software%29.

Here’s a list of important action words:

Checkout - Get the files from the repository for the first time.
Update - Get a version of the project, HEAD is the most recent version.
Commit - Make your changes happen in the repository; basically "check-in."
Add - Add a file to the repository. This won’t actually happen until you commit.
Delete - Delete a file from the repository. This won’t actually happen until you commit.
Export - Copy the files from the repository without the hidden .svn files.

Getting Set Up

Each repository has a separate list of users and passwords. If you don’t have access to a certain repository, talk to the subversion administrator. Right now, there is no way to set up a user or change a password without a subversion administrator being in the room with you. If it’s a big enough deal, this can be changed, but it might take up to a week to set up correctly.

Once you have access to the repository, you will need the url to the repository and a subversion client (see the following two sections.) Once you have both, you will need to give the client the url to the repository, your username, and your password to do your initial checkout. You can checkout starting from a subfolder (say /trunk) instead of the top level if you’d like. And then you’re all set up.

Please remember to make a log message whenever you do a commit to explain what you’re committing. Also, remember that the permissions for files are not checked in with a file. To make sure it's executable, you need to set a special permission, the svn-executable flag.

Subversion Clients

I’m going to list the subversion clients I know about and how to start using them. If you know the basics behind subversion, all these clients should be pretty intuitive to use once you’ve got them running. If you don’t know the basics of subversion, read the intro to http://svnbook.red-bean.com/.

Subversion Client: http://subversion.tigris.org/

This is the command line subversion client. To install it for Solaris, visit http://www.sunfreeware.com and get/install the subversion package for your version of Solaris. The utility will be located at /usr/local/bin/svn. To use this client, read the very easy to follow http://svnbook.red-bean.com/. If you only read the subversion client section (http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.ref.svn), it should be enough. I think this is the best client for UNIX systems.

Sample Commands:

Since you’ll be using the SVN Command line tool for now, here’s some samples on how to do things. I’ll assume /usr/local/bin/svn is on your path.

> mkdir /opt/repositoryName
> cd /opt/repositoryName
> svn checkout [repository url] .
> (possibly enter your username and password)

To do an update:
> cd /opt/repositoryName
> svn update

To do a commit:
> cd /opt/repositoryName
> svn commit

This will open an editor. Above the line is the log message. Below the line are the changes that will be committed. You can delete the lines you don’t want to be commited. To commit, do a :wq. To cancel, do a :q, and then specify abort.

To add a file:
> cd /opt/repositoryName
> svn add [filename]
> svn commit

To delete a file:
> cd /opt/repositoryName
> svn delete [filename]
> svn commit

Tortoise SVN (windows only): http://tortoisesvn.tigris.org/

In my opinion, this is the best subversion client on the windows side. It’s a simple, one click install. To use it, create a folder and then right click on it. Go to SVN Checkout and provide the repository information. All subversion operations will be available from the windows right click menu.

SmartSvn: http://www.syntevo.com/smartsvn/index.html

This is the easiest to install graphical svn client on the Solaris side. That is because it is a java program. This also means it’s probably the slowest of the graphical svn clients, but I’d say the easy install is worth it. To run it, run "[SmartSvnHome]/bin/smartsvn.sh." Please note you need java 1.4 to run it (which you should already have if you’ve installed NetBeans.) If your OS isn’t pointing to java 1.4 by default, edit the seventh line of [SmartSvnHome]/bin/smartsvn.sh.

RapidSvn: http://rapidsvn.tigris.org

This is another subversion client. It’s faster than smartsvn, but you’ll need to build it from source if you want to use if on Solaris. I like this graphical client the best on the Solaris side.

Tips for building RapidSvn:

1. A lot of compilation errors are probably due to your path. I needed to add /usr/local/bin:/usr/local/lib/:/usr/ccs/bin to my Path.
2. You’ll need to use the gnu make (which will install to /usr/local/bin) to make wxWidgets and Rapidsvn. Their make files are too big for Solaris’s preinstalled make.
3. You’ll need gtk 2 and glib 2 to compile wxWidgets. You might have to remove old packages (using pkginfo and pkgrm) to add them.
4. sunfreeware.com will list other dependencies the subversion package might need, so make sure those are installed if you’re having problems.
6. Basic Instructions for building RapidSvn:
a. Ensure /usr/local/bin:/usr/local/lib/:/usr/ccs/ are on your path.
b. Install all the necessary packages.
c. Untar wxWidgets and go into its folder, then type the following:
- ./configure -with-gtk
- /usr/local/bin/make (this will take about 2 hours full CPU)
- /usr/local/bin/make install
d. Untar rapidsvn and go into its folder, then type the following:
- ./configure
- /usr/local/bin/make (this will take about 1 hour full CPU)
- /usr/local/bin/make install
e. Try rapidsvn (/usr/local/bin/rapidsvn)

Subcommander: http://subcommander.tigris.org/

This is a pretty good graphical svn client, although it looks a bit ugly. It should already be installed on the windows side. This is a very difficult install for the Solaris side because you will need to build it from source. It has a lot of very huge dependencies so I eventually gave up trying to build it. You’re free to give it a try though.


For Would-be Subversion Administrators, a very brief guide

To complement the Subversion Client guide, I wrote this up. I probably shouldn't have because it's really, really brief and vague. But maybe it'll be helpful.

You will need to download and install subversion from http://subversion.apache.org. It is very likely that it's available for the platform you're using. If you're using Solaris, you can get the necessary packages from http://sunfreeware.com.

So follow the instructions and install subversion. Now I'm going into my personal preferences. I like to use apache as my subversion server, so make sure you've got that. Apache is easy to use, performs well, is easy to modify, and allows people to view your source without a subversion client on their machine. Now here's instructions on how I do my subversion set ups.

Create the directories [some path]/svn/users and [some path]/svn/repos.

All the repositories will be stored in [root]/svn/repos. To create a new subversion repository, open a command line prompt, go to [root]/svn/repos, and type the following commands:

> svnadmin create [name_of_new_repository]
> [path to apache's htpasswd]/htpasswd -c /svn/users/[password name] [firstuser]
> [Enter Password]
> [Create the initial layout of trunk, branches, and tags folders]

Now that the new repository is created, you will need to serve it. To make the new repository available, you will need to edit httpd.conf and then restart the Apache (you can use the apache monitor in the taskbar to restart.) The configuration for the new repository in the httpd.conf file should look something like this:

DAV svn
SVNPath /svn/repos/[repository name]
AuthType Basic
AuthName "[repository name]"
AuthUserFile [root]/svn/users/[passwords file]
Require valid-user

The password files for the repositories will all be stored in /svn/users. Each repository has its own password file. Look into the httpd.conf file to figure out which repository uses which password file, but the file names should make it fairly obvious. To create or edit a user’s password, open a command line prompt, go to /svn/users, and type the following commands:

> [path to apache's htpasswd]/htpasswd [password file name] [username to edit/create]
> [enter password]
> [verify password]

Unfortunately, there is currently no way easily change passwords remotely. Password management can be done in many ways, like through Apache features or through a Web Application, but doing it would be a fair amount of effort to set up without any previous experience.