Subversion - A Quick Tutorial

I don't know how I managed to survive for years without some sort of version control [1] for my personal projects. First, I used to manually make backup copies of my project directory in case I wanted to revert back or compare revisions. Later, I relied on Eclipse [2] for a very basic version control system. Eclipse stores copies of project files after every save, and lets you compare revisions. Next, I decided to write a script that made backup copies of my projects directory, and archived them according to date/time.

Finally, and given that I have been using CVS to contribute to various Open Source projects for a long time, I saw the light and decided to utilize a version control system for my own projects.

I have been hearing about Subversion [3] for a while, but never had the chance to read more on or try it out. So I decided to experiment with it instead of going directly with CVS [4]. First, it started as "trying something new" but later I realized Subversion has new features that cover many limitations of CVS. I'm no guru of either, but here's what I found:

• Subversion tracks structure of folders. CVS doesn't have the concept of folders.
• Subversion has a global revision number for the whole repository. CVS tracks each file individually. A commit that represents one logical change to the project code may change a group of files; in Subversion, this commit will have one revision number instead of separate revision numbers for every changed file in CVS.
• Subversion commands are very similar to CVS. It's very easy to switch for CVS users. Most of the time it's a matter of replacing cvs with svn.

Again, I don't know all ins and outs of CVS or Subversion, if I'm missing anything, please correct me!

It took me less than an hour to experiment with Subversion, learn it, and import my projects to it. So I decided to write a quick tutorial for those who:

1. Are already familiar with version control systems (like CVS).
2. Haven't used any for controlling their local projects.
3. Would like to try Subversion.

If this is not your case, I point you to "Version Control with Subversion [5]" where I started reading about Subversion.

Read on for the quick tutorial.

Installation

The first step for using Subversion is installing it. This depends on your system. For us, Gentoo [17] users, we can get Subversion going with one command:

# emerge subversion

Subversion has packages for many systems [18], Linux (Gentoo, Debian, Fedora, ...), Mac OS X, FreeBSD, Windows, ...

Creating The Repository

The first Subversion tool we will use is svnadmin. This tool is for administration tasks, like creating repositories, making backup dumps, and the like. To create a repository, open the command line, change the current directory to where you want to create it, and run svnadmin:

$ cd /home/ayman
$ svnadmin create svn

I called my repository svn. You can call it whatever you like. Subversion uses this directory to store information about your projects, like file revisions. You won't need to directly deal with this directory, so I suggest keeping it in a safe place and not tinkering with its contents unless you know what you're doing.

Importing Projects

Now that we have a repository, we will use the svn tool to import and manage projects. To import a project, first create a directory for it in your repository. To do so run svn mkdir:

$ svn mkdir file:///home/ayman/svn/myproj

Subversion will open your default text editor and ask you to enter a log message. Enter an explanation of what you're doing, save, and exit the editor.

Next, it's time to import project files. Change the current directory to the project's directory, and run svn import:

$ cd /home/ayman/[...]/myproj
$ svn import file:///home/ayman/svn/myproj

Check out, Modify, Commit

As I said, the repository is stored in the svn directory which you won't deal with. To work on your files, first you need to check a working copy out of the repository. To do so, use svn checkout:

$ svn checkout file:///home/ayman/svn

A new directory named myproj will be created containing your project files. You can work and modify them. Once you're done and you want to store the new revision in your repository, run svn commit in the checked-out myproj directory:

$ svn commit

Subversion will open your default editor asking for a log message. Again, enter an explanation, save, and exit.

Working with Revisions

Now let's make real use of Subversion. While working with revisions, you can:

Check Status

$ svn status [filename]

Compare different Revisions

$ svn compare -r R1:R2 [filename]

Revert Local Edits

$ svn revert [filename]

Revert to Previous Revisions

$ svn update -r R

[filename] is optional; you can run the previous commands on the current directory if you omit it.

A Final Word

This is a very quick start for using Subversion to control local projects. For extended help on commands, you can always use svn help [command] to get a help message on [command], for example:

svn help import

In addition, check out "Version Control with Subversion [5]" for detailed information.

Good luck, and happy subversion'ing!