Subversion - A Quick Tutorial

Subversion - A Quick Tutorial

Subversion is a version control system that is widely used by many Open Source projects such as Apache and GCC. Subversion started as a project to implement features missing in CVS. Some of these features are:

• 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 commits are atomic.
• Subversion retains the revision history of moved or copied files.

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. The following is a tutorial and cheat-sheet to help you get up and running in Subversion quickly.

• Installation
  • Creating the Repository
    • Importing Projects
    • Check out, Modify, Commit
    • Working with Revisions
      • Check Status
      • Compare different Revisions
      • Revert Local Edits
      • Revert to Previous Revisions
    • Final Word

Installation

The first step for using Subversion is installing it. This depends on your system. In Ubuntu and Debian, it a matter of running the following command:

$ sudo apt-get install subversion

Subversion has packages for many systems, 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 created my repository under my home directory: /home/ayman)

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

(Replace /home/ayman/svn/myproj with the actual path to your repository and the new project name)

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

(This will import all files under /home/ayman/[...]/myproj to the newly-created myproj directory in your repository)

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>

(Replace R1 and R2 with actual revision numbers you want to compare)

Revert Local Edits

$ svn revert <filename>

Revert to Previous Revisions

$ svn update -r R

(Replace R with an actual revision number)

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

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

This will give a detailed explanation on svn import.

In addition, check out "Version Control with Subversion" for more information.

Good luck, and happy subversion'ing!