Source control programs manage changes to a software project and allow multiple programmers to work together without destroying each other's work. Even for a single programmer, source control will allow you to create branches of the same project for different clients, or to rollback changes to an older version of the project. The most popular source control programs for Linux are CVS and Subversion. This page discusses how to get started with Subversion (SVN).

Many Linux IDE's have built-in support for CVS and subversion but they usually expect you to be familiar with source control concepts.

 Subversion Concepts

Subversion stores the project in a directory called the repository. This is a kind of database that records all the files and changes in the project.

There are three basic Subversion activities:

• Check Out - get a copy of a project
• Update - automatically patch your copy with any changes made by other developers
• Commit - submit your changes to the other developers. The project must be updated before it can be committed.

Subversion documentation is located at http://svnbook.red-bean.com/. The subversion home page is http://subversion.tigris.org/.

 Major differences compared to CVS

Subversion is intended to be an enhanced version of CVS. Some of the differences are:

• the repository is referred to as a URL (e.g. file: or http:)
• permissions are handled better
• can rollback if there is a problem
• faster performance

 Setting up Subversion

To begin using Subversion, create a subversion user and a repository to hold the shared files. Since this user will own the repository, it's important to get the permissions correct. For example, create a user "svn" with group "svn" and then add group "svn" to everyone who will access the repository. Make sure the repository has write access for the group.

For example,

   useradd -d /srv/svn -s /bin/false svn ; groupadd svn

Alternatively, you should make the svn user's group the group of the developers, if your developers have a group like "develop" to be shared by all developers.

Now you have a user to own the subversion repository, login as root and create the repository with svn. /home/repository/svn or /srv/svn might be good choices for a repository, depending on your system. (SuSE Linux puts server directories under /srv.) The /home directory is often on a separate partition to protect it from Linux distribution upgrades. It's also a good practice to back up /home (or /srv) on a regular basis and this will save your projects at the same time. The repository cannot be the home directory of the svn user (the directory must not exist): either delete the home directory first or put the repository inside the home directory.

   svnadmin create /home/repository/svn

Make sure the repository is owned by svn and is writable by the people using subversion.

Subversion uses URL's to refer to the respository and the projects stored inside of it. If the respository is /home/repository/svn/svnroot:

• file:///home/repository/svn/svnroot - the repository on the local machine
• http://other/home/repository/svn/svnroot - the repository is on the machine called "other" and is accessed through Apache WebDAV
• svn://other/home/repository/svn/svnroot - the repository is on the machine called "other" and is accessed through svnserve
• svn+ssh://other/home/repository/svn/svnroot - the repository is on the machine called "other" and is accessed through Secure Shell (SSH)

To create a new project in Subversion, create a new directory in the repository for it. Suppose you want to create a new project called "test_project".

   svn mkdir file:///home/ken/test_repository/test_project --message="Test Project Created"

If "test_project" is an existing project in a "test_project" directory, import that directory into the respository:

  svn import test_project file:///home/ken/test_repository/test_project

It's a standard convention in Subversion to create three subdirectories in the project directory: "trunk", "tags" and "branches". These subdirectories are used when working on alternate versions of a project. They are not required and for simple projects they are not necessary.

To work on a project, "check it out" with svn co. If the destination exists, it adds Subversion support to the project without overwriting anything or adding any files officially to the project.

   svn co file///home/ken/test_repository/test_project

 Working on a Subversion Controlled Project

To update your project with the latest changes by your fellow programmers, type:

  svn update

You can also update individual files (instead of the directory) by naming files in the command.

To commit your changes to the project so they can be seen by your fellow programmers, type:

  svn commit --message="Added new features"

You can also commit individual files (instead of the whole directory) by naming files in the command. To avoid typing in descriptions, you can include a description of the changes using -m "message" where message is the description to put in the CVS change logs.

 Using Subversion Remotely

To use Subversion remotely, the most common method is over a Secure Shell connection (SSH). Create a secure shell connection and setup your SSH authentication keys so you won't have to type a password. If you've never used SSH, you'll need to generate a pair of SSH keys (e.g. ssh-keygen -t rsa), copy the public key (.ssh/id_rsa.pub) to the remote home directory (or add it) (.ssh/authorized_keys) and make sure the remote key file is not world readable (otherwise it is an automatic rejection by SSH).

To access the repository, refer to it by the svn+ssh URL protocol. This will automatically start Subversion on the computer with the repository (running under your login so all files submitted to the repository are owned by your account).

  svn mkdir svn+ssh://armitage/home/repository/svn/svnroot/test_project --message="Project Directory Created"

If you have to go through a firewall, make sure that the secure shell (port 22) is allowed through to the computer with the repository.

 Using Subversion Remotely on a Different Port

Sometimes you may want Subversion to work through a different network port than the SSH default. For example, you might be port forwarded through a firewall to a particular machine. Alternatively, port 22 might be used to SSH to a firewall and another port will need to be used to SSH to an internal machine. Subversion handles this through your personal configuration file (~/.subversion/config). Create a config file and add a "tunnels" section with the ssh command information. For example, to use SSH through port 29934:

      [tunnels]
      altssh = $ALTSSH /usr/bin/ssh -p 29934

When you use the repository URL, use "svn+altssh://" instead of "svn+ssh://" and Subversion will use the alternate ssh command that you specified. (If the shell variable $ALTSSH exists, the command in it will be used instead.) You can set up any number of alterative tunnels: use a different name for each.

 Using Subversion to Rollout Projects

You can sometimes use Subversion to rollout projects, especially web sites. On the production machine, move to the root web directory and use Subversion to update the web site (or check out the web site if this is the first time). This will create Subversion .svn directories (as if the web site was a developer) but it will also update the files on the entire web site. Check file ownerships and permissions as needed.

Documents or web pages can have RCS dollar tags embedded in them. When Subversion updates a project, it searches files for dollar tags and replaces them with information about the project. You can use dollar tags in web pages to automatically report when pages were updated and who last changed them. This can be useful for research papers, reports or other material that can become outdated.

This is a basic tutorial. Read the Subversion documentation for more features.