27.5. Introduction to Subversion

Subversion is a free open source versioning control system and is widely regarded as the successor to CVS, meaning that features already introduced for CVS are normally also in Subversion. It is especially recommended when the advantages of CVS are sought without having to put up with its disadvantages. Many of these features have already been briefly introduced in Section 27.1.3, “Subversion”.

27.5.1. Installing a Subversion Server

The installation of a repository database on a server is a relatively simple procedure. Subversion provides a dedicated administration tool for this purpose. The command to enter for creating a new repository is:

svnadmin create /path/to/repository

Other options can be listed with svnadmin help. As opposed to CVS, Subversion is not based on RCS, but rather on different types of repository. The Berkeley Database or FSFS (a repository that uses the file system directly) is commonly used. Do not install a repository on remote file systems, like NFS, AFS, or Windows SMB. The database requires POSIX locking mechanisms, which these file systems do not support.

The command svnlook provides information about an existing repository.

svnlook info /path/to/repository

A server must be configured to allow different users to access the repository. Either use the Apache Web server with WebDAV to do this or use svnserve, the server packaged with Subversion. Once svnserve is up and running, the repository can be accessed with a URL with svn:// or svn+ssh://. Users that should authenticate themselves when calling svn can be set in /etc/svnserve.conf.

A decision for Apache or for svnserve depends on many factors. It is recommended to browse the Subversion book. More information about it can be found in Section 27.5.3, “For More Information”.

27.5.2. Usage and Operation

Use the command svn (similar to cvs) to access a Subversion repository. With svn help, obtain the description of a parameter of a command:


checkout (co): Check out a working copy from a repository.
usage: checkout URL[@REV]... [PATH]

  If specified, REV determines in which revision the URL is first
  looked up.

  If PATH is omitted, the basename of the URL will be used as
  the destination. If multiple URLs are given each will be checked
  out into a sub-directory of PATH, with the name of the sub-directory
  being the basename of the URL.
...

The content provided by a correctly configured server fitted with a corresponding repository can be accessed by any client with one of the following commands:

svn list http://svn.example.com/path/to/project

or

svn list svn://svn.example.com/path/to/project

Save an existing project in the current directory (check it out) with the command svn checkout:

svn checkout http://svn.example.com/path/to/project nameofproject

Checking out creates a new subdirectory nameofproject on the client. Operations (adding, copying, renaming, deleting) can then be performed on it:

svn add file
svn copy oldfile newfile
svn move oldfile newfile
svn delete file

These commands can also be used on directories. Subversion can additionally record properties of a file or directory:

svn propset license GPL foo.txt

The preceding example sets the value GPL for the property license. Display properties with svn proplist:

svn proplist --verbose foo.txt
 Properties on 'foo.txt':
 license : GPL

Save the changes to the server with svn commit Another user can incorporate your changes in his working directory by synchronizing with the server using svn update.

Unlike CVS, the status of a working directory in Subversion can be displayed without accessing the repository with svn status. Local changes are displayed in five columns, with the first one being the most important one:

' '

No changes.

'A'

Object is marked for addition.

'D'

Object is marked for deletion.

'M'

Object was modified.

'C'

Object is in conflict.

'I'

Object was ignored.

'?'

Object is not being maintained by versioning control.

'!'

Object is reported missing. This flag appears when the object was deleted or moved without the svn command.

'~'

Object was being maintained as a file but has since been replaced by a directory or the opposite has occurred.

The second column shows the status of properties. The meaning of all other columns can be read in the Subversion book.

27.5.3. For More Information

The first point of reference is the home page of the Subversion project at http://subversion.tigris.org/. A highly recommendable book can be found in the directory file:///usr/share/doc/packages/subversion/html/book.html after installation of the package subversion-doc and is also available online at http://svnbook.red-bean.com/svnbook/index.html.