Subversion notes

I like to keep personal files in my home directory under source control. Over the years, I've used SCCS, RCS, CVS, and now Subversion. (I've used Visual SourceSafe and ClearCase strictly for work.) Anything that requires occasional editing deserves source control, such as login profiles, utility scripts, code, personal website, and any research documents or notes.

The best reference is this Creative-Commons book, also available from O'Reilly: http://svnbook.red-bean.com/

§    Why not stay with CVS?

SVN is essentially a complete rewrite of CVS, which is now unsupported and obsolete. For some time now, former CVS developers have put their effort into enhancing SVN. The 1.0 version of SVN had 100% of the functionality of CVS.

Most run the SVN service as a secure Apache plugin, rather than as a special purpose server. This has allowed much more web-based enhancements than were ever available for CVS. Here are examples of reports: http://mpy-svn-stats.berlios.de/zope-stats/

Apache is the most popular webserver on the web, and the most heavily audited for security vulnerabilities.

Whenever possible, SVN commands have the same name as for CVS, such as "add," "remove," "checkout," and "update." New names were introduced when simpler and more obvious, such as "move," "copy," "mkdir," and "revert." Unlike CVS, all commands seem to work as expected without any flags at all. I no longer need aliases or scripts for common chores. As a former CVS user, you can start with "svn help" and quickly figure out the rest.

Changing the names of directories and files is now trivial and causes no duplication in the repository. Copies retain the history of their sources. CVS always discouraged refactoring by remembering changes only for a certain file in a certain directory. Now directories are versioned as well.

You no longer need to distinguish binary and text files: all are compressed and differenced with a binary algorithm. Yet, you can specify that certain text files will receive an extra carriage-return on Windows(TM).

The complicated branching and tagging in CVS is now handled in SVN by a simple intuitive copy of an entire directory, without any actual duplication in the repository. Merging is also much more intuitive and less error-prone because you can see multiple branches at once.

Working copies of CVS require constant access to a repository simply to see what local changes have been made to the code. SVN allows you to see those changes and undo them without any contact with the repository.

Here are other substantial improvements over CVS: http://svnbook.red-bean.com/en/1.1/ch01s03.html All files can contain useful metadata. Symbolic links are handled automatically. All commits are atomic and cannot result in inconsistent state.

§    New repository

I think it is best to keep unrelated base directories as entirely separate SVN repositories.

First I create a top-level directory $HOME/mysvn/ to contain all the individual repositories.

Here's how to create a new repository from a directory outside of source control. 
  SVNHOME=$HOME/mysvn
  mkdir $SVNHOME

  project=foo
  svnadmin create --fs-type fsfs $SVNHOME/$project

  SVNURL="file://$SVNHOME"
  svn mkdir $SVNURL/$project/branches -m "first version"
  svn mkdir $SVNURL/$project/tags -m "first version"
  svn mkdir $SVNURL/$project/trunk -m "first version"

  cd $HOME/$project
  svn import . $SVNURL/$project/trunk

I strongly recommend using the new "fsfs" file system rather than the older Berkely database. BDB requires a local filesystem with full POSIX locking and memory mapping. NFS disks will be unusable. There are many other drawbacks and no significant advantages to BDB.

§    Converting from CVS

Here's how I convert a preexisting CVS project to SVN. 
  SVNHOME=$HOME/mysvn
  mkdir $SVNHOME

  project=foo
  svnadmin create --fs-type fsfs $SVNHOME/$project

  cd /tmp/
  CVSROOT=$HOME/mycvsroot
  cvs2svn --use-cvs --existing-svnrepos --trunk-only --keywords-off \
   --no-default-eol -s $SVNHOME/$project $CVSROOT/$project

The --use-cvs flag is much slower, but avoids possible rcs format errors.

I turn off keyword expansion and eol changes to avoid corrupting binary files that were not properly checked into CVS as binaries.

If you have no binary files you may omit the --no-default-eol flag. If you are editing files on both windows and unix, then you will want to add this property later with something like 
find . -name '*.txt' | grep -v '\.svn' | 
  xargs svn propset svn:eol-style native

§    Making a working directory

Once the project is checked in, I replace the existing one. 
  SVNHOME=$HOME/mysvn
  SVNURL="file://$SVNHOME"
  project=foo

  cd $HOME
  mv $project $project.original

  svn checkout $SVNURL/$project/trunk $project
[or]
  SVNREMOTE="svn+ssh://$HOSTNAME/$SVNHOME/"
  svn checkout $SVNREMOTE/$project/trunk $project

§    Breaking apart a repository

You may want to break subtrees of a repository into multiple repositories. Or you may want to reclaim space by deleting a part of your tree permanently.

You'll need need to dump the repository with svn dump, filter through svndumpfilter, then load into a new repository. See the RedBean book for details.

Bill Harlan, 2005-2007

Return to parent directory.