A simple introduction to using SVN

SVN is advertised as a compelling replacement for CVS, and stands for Subversion. It is a software engineering tool (but let that not scare you off yet) to do version control. It will basically help you keeping versioned backups of your files. You will always be able to retrieve the state of your project at any give date/stage you had been in. This page will simply introduce how you can do this for yourself on a single machine. SVN is far more powerful and you can also share your work with (remote) collaborators. Don't think just of software development, but also of writing proposals and papers. It is also independant of the operating system, so one author can use linux, another one MacOSX and even Windows is allowed. The infamous CR-LF problem in text files is automatically taken care of by SVN. Even if you make mistakes, SVN keeps all your versions in a database. There is even a description how SVN (or CVS) can be used to keep track of your shell login files, very handy if you keep having to make accounts on different machines.

Enough for introduction, lets get down to a simple example how you use SVN just for your own work that you do not want to share with others, but you do want to be able to keep backups and multiple versions.

1. Initial setup

Suppose you have an existing directory /tmp/paper1 that you want to put under SVN control. The very first time you'll need to make the initial svn repository (the svn database) within which eventually all your files and projects will be stored. For clarity, I will use an absolute path name /tmp in the examples below, but you can of course use local and relative pathnames as well: 
   % svnadmin create /tmp/svnroot
(not needed, but you are allowed to make this directory). You will already see a few files and directories, a little over 100KB, in that new directory. Normally you would never have to do anything in this directory. I am also assuming your paper1 directory only contains the files you care about, not temporary .o or .dvi files that might have been created by applications. So, to import the paper1 into SVN, do this: 
   % svn import /tmp/paper1 file:///tmp/svnroot/paper1 -m "initial import"
As said, you cannot use normal Unix commands to look at your files in the SVN repository. They are neatly hidden and protected from tinkering in the /tmp/svnroot directory. The svnlook command will give you a listing: 
  % svnlook tree /tmp/svnroot
Now, the paper1 tree should normally contain all (and only those) files you want to keep under SVN control. Any temporary files you create later, would not be part of SVN and lost. An example are dvi files if you work on a latex paper. You generally do not want them under SVN control, so the paper1 directory should be clean of files you normally don't care about. 
   % rm -rf paper1
   % svn checkout file:///tmp/svnroot/paper1 paper1
   % cd paper1
   % more .svn/entries
   % svn delete paper1.dvi
   % svn update

2. Working with sandboxes

Inside a sandbox (the directory tree you checked out with the svn checkout command) you will edit files, maybe add new files/directory, or remove, and these will generally only require 3 svn commands to control (CVS users will notice these are identical to the ones in CVS): 
    % svn commit 
    % svn update
    % svn add chaper5.tex
svn commit will store all files in your current sandbox (include subdirectories) back into SVN.

svn update will synchronize your current sandbox with any new files somebody may have commited before to SVN.

svn add will tag new files or directories for a next commit command

3. Local Configuration

Either set the SVN_EDITOR environment variable in your shell startup file (.cshrc or .bashrc), or set the editor-cmd= in the ~/.subversion/config file. I prefer the latter.

4. Upgrading your simple SVN repository to be used by others

At some point you might decide to give collaborators read and/or write access to your work.

There are several options how to upgrade your SVN repository for others to use:

  1. Create tar files of your project on a regular basis (crontab?) and make those available via anonymous ftp or a webserver. This is not really an SVN upgrade, but it is an easy option to give SVN snapshots to others.
  2. On the same system you give write permission to the svnroot tree and instruct your collaborators to use the same file:/// notation. Note you cannot use NFS mounted filesystems for svn
  3. If your collaborators have an account on your system, use the svn+ssh:// protocol.
  4. If your collaborators are remote, and not too bothered by firewalls that might block port 3960, use the svn:// protocol
  5. Install some svn plugins on your apache server, setup that server in the right way and use the http:// protocol.
These 5 options are also roughly listed in order of complexity. Creating tar files from clean sandboxes is easy ('svn export' and 'tar'). Setting up an apache server and added SVN access is not very hard, but does take some time to master.
Some links: