Technocrat's Weblog

Thu, 22 Sep 2005

Subversion Primer

Introduction

A version control system allows multiple people to work concurrently on many files without over writing each other's work. CVS is one of the most commonly used version control systems. Subversion was built as a replacement for CVS. Subversion has features similar to CVS. Additional features that the developers felt were lacking in CVS:

The following is a primer on the basics of Subversion. Note that the code examples refer to the repository using the URL file:///. This type of URL is used only if the user is working on the same system where the repository resides. To access the repository remotely, the user can do so via ssh. In that case, the URL would be svn+ssh://

Creating a repository

Subversion offers two different formats for the storing of a repository and its control files: Berkeley DB or FSFS. Since FSFS is now the default format for Subversion it will be used in these examples.

A new repository can be created using the svnadmin command.


svnadmin create --fs-type fsfs /opt/svn

This command will create the directory svn and the Subversion control files. Be sure that the permissions on the repository directory are sufficient. Pay careful attention to group permissions so that everyone that needs write access can have it. It will also be useful to set the group sticky bit on the repository's db directory. This will ensure that commits do not prevent other users from performing future commits.

Imports

To initially import projects into Subversion gather the projects and files. Arrange them in a desired directory structure. For example:


#> pwd
~/tmp/svn
#> find
./scripts
./scripts/encryption
./scripts/encryption/secrets
./scripts/html
./scripts/html/csv2html
./scripts/profile
./scripts/profile/.profile
./scripts/profile/.vimrc
./scripts/profile/.procmailrc
./scripts/profile/.muttrc

Now import this tree into Subversion:


svn import . file:///opt/svn --message "Initial import"

Projects are now ready to checkout.

Checkouts

Checkout code to a working copy:


svn checkout file:///opt/svn/profile

Any subdirectory in the repository can be checked out. This allows the user to checkout a portion of a project thus shorting the checkout time.


svn checkout file:///opt/svn/profile/.vim

This works for a directory only. We can view a single file using svn cat but this is not a true checkout.


svn cat file:///opt/svn/profile/.profile
In the working copy there is a directory named .svn. This directory contains a copy of the checked out code and various control files. These contents are never changed by the user. Subversion uses the contents of this directory to manage the working copy. Never alter this directory or its contents.

Working with a working copy

To update your working copy to match the repository:


svn update <file>

Warning, this could overwrite your working changes.

Other useful commands:


svn diff
Display all the differences between the working copy and the repository in diff format. This output can be used with the patch program. 

svn revert <file>
Revert file to its premodified state. 

svn add <file>
Schedule file, directory or symbolic link to be added to the repository during the next commit. 

svn copy <file> <file>
Copy one file, directory or symbolic link to another name. The copy is scheduled to be added to the repository during the next commit. 

svn delete <file>
Schedule one file, directory or symbolic link to be removed from the repository during the next commit. 

svn move <file1> <file2>
Move works the same if copy was performed and the original deleted. 

svn status
See the changes made to working copy without any commits. 

svn log
See commit log of the working copy.

When changing the structure of the working copy such as moving, deleting or adding files, be sure to use the above commands. If not, Subversion may not be properly aware of the changes at commit time.

Commits

To commit the working copy to the repository:


svn commit --message "Your log message"

Note that only the necessary files are transferred to the repository. If the message switch is left out, svn will open an editor, defined by the SVN_EDITOR environment variable, where a commit log can be written. The --file switch can be used instead. The --file switch should point to an existing log file.

Backups

A direct backup of the repository should not be performed. If a commit were to take place during the backup, the revision history in the backup could be incorrect. Subversion provides a tool to make a hot copy. A hot copy is a complete backup of the entire repository. The hot copy may be copied to backup via the usual methods (e.g. tar) without fear of interfering commits.


hot-backup.py /opt/svn /opt/svn-backup

Further reading