Listen Print Discuss

Single-User Subversion

by Rafael Garcia-Suarez
10/31/2002

Subversion is an open source revision control system, similar in purpose to the well-known, widely deployed, and aging CVS. It is designed to provide state-of-the-art versioning, built from modern technologies.

Subversion is still in development and has not reached version 1.0 yet. However, it's pretty stable and you can use it right now. In this article, we'll cover the basics of Subversion, how to install it, and how to use Subversion for personal projects. A future article will cover installing and using a multi-user, networked Subversion server.

What's Subversion For?

In short, Subversion helps developers to track changes in their project source files. You might ask why you would need a revision control system for your home projects, where you are the only person who decides how and where to make changes. There are several reasons: to retrieve and to compare previous releases, to hunt down regression bugs, to maintain backward-compatible branches, to produce neat changelogs, to work on two different fixes or improvements without confusion. Moreover, you'll get all this with little expense, because Subversion is surprisingly easy to install.

A Subversion repository acts as a filesystem that remembers sets of changes made to it. It does this by storing files in a tree structure, tracking its evolution over time. The repository increments a global revision number with every set of changes committed into the repository. As the whole tree is versioned, it acts as a regular filesystem. Copying and renaming files is possible; creating a project branch is as easy as copying a directory. You can also ask Subversion to produce a difference between two arbitrary revisions, or to check out some subtree at revision N.

Installing Subversion

This section covers the installation of Subversion on Unix-like systems. (It's also possible to build and install Subversion on Windows. See the INSTALL file of the Subversion distribution.) To install Subversion, you may have to upgrade (or install) some of the tools on your system (autoconf, libtool, python2). You'll need also the expat XML parsing library. For detailed info, see the BUILD REQUIREMENTS section of the INSTALL file. Subversion is built completely on open source components.

Subversion requires also a recent version of the Berkeley DB. Be sure to check the README and INSTALL files to make sure you have the correct version. (As of this writing, Berkeley DB 4.0.14 worked.) Subversion uses this database as the underlying storage for its repositories. You can get it from Sleepycat Software.

The Subversion snapshots, available from the main Subversion site, include all of the other libraries needed to install a local repository. Building a network-accessible Subversion server requires Apache 2, but that's another article. The INSTALL file also explains how to check out a fresh new Subversion from the repository (yes, the developers of Subversion do use their own software), but that's not absolutely needed as Subversion is becoming more stable. We'll use a snapshot. As of this writing, the revision number of the latest snapshot is 3578 (a.k.a. Subversion 0.14.5), but let's call it XXXX.

Subversion development proceeds rapidly. To make upgrades easier, we'll install Subversion in its own subdirectory. We'll also assume that you need to install the appropriate version of the Berkeley DB. Commands prompted by a # should be run as root. (If you don't have root access, install Subversion in your home directory instead of using /usr/local as in the examples below.) 

# mkdir /usr/local/subversion-rXXXX
# ln -s /usr/local/subversion-rXXXX /usr/local/subversion

$ gunzip -c db-4.0.14.tar.gz | tar xf -
$ cd db-4.0.14/build_unix
$ ../dist/configure --prefix=/usr/local/subversion-rXXXX
$ make

# make install

Make sure your system can find libraries in /usr/local/subversion/lib. This is generally accomplished by setting your system's equivalent to the environment variable LD_LIBRARY_PATH. On Linux, you can also add this path to your /etc/ld.so.conf file and run /sbin/ldconfig. Then, build Subversion:

$ gunzip -c subversion-rXXXX.tar.gz | tar xf -
$ cd subversion-rXXXX
$ ./configure --with-berkeley-db=/usr/local/subversion-rXXXX \
	--prefix=/usr/local/subversion-rXXXX
$ make
$ make check         # optional : runs the tests

# make install

Finally, add /usr/local/subversion/bin to your PATH. That's it!

Create a repository

The next step is to create a repository to store your files. I'll put my repository in /home/rafael/svn, as I have plenty of room on this partition.

$ cd /home/rafael
$ svnadmin create svn

I have now a directory, /home/rafael/svn, containing my repository. It contains no files and has a revision number of 0. I'll fix that by importing a source tree.

Suppose I'm working on a frobnizer. To create a directory frobnizer at the root level of the repository, and to import the contents of my tree /home/rafael/frobnizer, the appropriate command is:

$ svn import file:///home/rafael/svn /home/rafael/frobnizer frobnizer

Why the URI in the above command? The few svn commands that need to deal directly with a repository refer to it by a URL. file:// URLs refer to repositories on a local disk. Subversion also supports http:// and https:// URIs for remote, Apache-powered Subversion servers.

In fact, in order to organize your repository better, it's preferable to create a directory for your project, importing your files into a trunk subdirectory. We'll see the precise reasons for it later. Instead of the above command, use:

$ svn mkdir file:///home/rafael/svn/frobnizer -m 'Create frobnizer project'
$ svn import /home/rafael/frobnizer file:///home/rafael/svn \
	frobnizer/trunk -m 'Initial import of frobnizer project'

The first command, mkdir, creates an empty subdirectory, frobnizer. It also labels this change with the log message Create frobnizer project. The second command performs the actual import, adding its own log message.

You can create as many repositories as you like. If you work on several different, unrelated projects, you may want independent repositories for each. This will enable you to handle and to move them separately later.

Check out a working copy

You don't work directly in the repository. To make changes to your files, you must check out a working copy of the whole repository or of one of its subdirectories. To do this, use checkout, performed here in a new frobwork directory:

$ svn checkout file:///home/rafael/svn/frobnizer ~/frobwork

This working copy contains all files that you've checked out, and you can now safely edit them. Hidden .svn subdirectories will also contain client-side state data. These files allow Subversion to perform some operations without dealing directly with the repository. This allows you to work off-line even if the repository is normally network accessible.

Pages: 1, 2

Next Pagearrow