Subversion

This page is about 'Subversion' which is more commonly known as svn.

if you need help migrating to git then call Greg Rundlett at eQuality Technology

Architecture

Documentation and Resources

http://www.digilife.be/quickreferences/QRC/Subversion%20Quick%20Reference%20Card.pdf
The Book (all versions) including
Best Practices
The project website at tigris.org
SVN Release Notes
- v 1.3
- v 1.4
- v 1.5
subversionary.org community (Subversionary site runs on Drupal)
orcaware.com wiki (the wiki at orcaware runs on MediaWiki)
svnforum.org forums
Vendor Support CollabNet offers full support and enterprise services for Subversion as the company behind the software project.
Pragmatic Version Control is a great book on some of the implementation topics.

Subversion Clients

Subversion clients are available for all Operating Systems. The powerful command-line client comes with the software. More details are on the Subversion/client page.

Administration

Managing Users

To add a user, or change their password sudo htpasswd -m /etc/apache2/auth/svn-auth-file username To give the user access to repositories sudo vi /etc/apache2/auth/svn-access-file

This simple procedure works well for modest-sized groups, but fuller methods of authentication and group management such as LDAP authentication and authorization will likely be the best solution in a larger setting.

Software Installation and Initial Configuration

See http://gentoo-wiki.com/HOWTO_Apache2_with_subversion_SVN_and_DAV in addition to the manual.

Some of the key items for an install:

narrow your server options: we use Apache exclusively. We were using file:// but that uneccessarily complicates the security model and administration of user/system accounts and groups.
create a svn group so that you can add authors to that group
create wrappers (including apachectl) to set umask 0002 for some access
set group ownership on the 'db' and set group sticky bit

Migrating a repo from one host to another

To start with, do a dump of the repo

svnadmin dump /var/svn/oasis > /home/me/svndump-2006-12-20

Since the dump file is a human-readable format, it can be compressed considerably. In our case, the uncompressed file is 9GB, so compression is a big timesaver for sending it across the wire. You could compress it in transit using rsync's -z option, or you could use gzip or bzip to compress and decompress on the fly.

tar cf - ./svndump-2006-12-20 | gzip -9 | ssh grundlett@10.21.20.10 tar xzf - -C /home/grundlett

The configuration file is conf/svnserve.conf, however you MUST be familiar with all the repository tools (especially svnadmin) that come with SVN before you do anything manually on the filesystem. Each repository comes with this warning in the README:

This is a Subversion repository; use the 'svnadmin' tool to examine it. Do not add, delete, or modify files here unless you know how to avoid corrupting the repository.
If the directory "db" contains a Berkeley DB environment, you may need to tweak the values in "db/DB_CONFIG" to match the requirements of your site.
Visit http://subversion.tigris.org/ for more information.

Administration tools

Note that many clients come with repository manipulation features

svnadmin

svnadmin is the primary administration tool that comes with Subversion

Among other things, it can list locks in the repository with lslocks

general usage: svnadmin SUBCOMMAND REPOS_PATH

[ARGS & OPTIONS ...] Type 'svnadmin help <subcommand>' for help on a specific subcommand.

Available subcommands:

create
deltify
dump
help (?, h)
hotcopy
list-dblogs
list-unused-dblogs
load
lslocks
lstxns
recover
rmlocks
rmtxns
setlog
verify

Command Reference

Locking Files

Dealing with binary files (e.g. *.doc, *.jpg) Note that sometimes it is useful to work with 'locks' to advertise to other users that you are editing a binary file format like a jpg or doc (since binary files don't merge particularly well). Subversion enables you to create a lock on a file. You can also find out who has the file locked. Locks are not authoritative. You don't just create a lock and forget it. You don't create a lock just to prevent others from working. By policy, (long-lived ~72hr) locks can and will be broken by the repository administrator. Locks can also be stolen (somebody else needs to work on the file, you forgot your lock was on it, they broke your lock and then lock the file themselves so they can advertise that they are working on the file. If you have wide-area access control issues, speak to a repository administrator about the authorization permissions for a project.

http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.advanced.locking

Subversion Help

Subversion has a very extensive help interface available. To see the top-level help, run:

svn help

From there, other commands can be investigated by adding those commands like:

svn help add
svn help delete
svn help commit

Adding a file

svn add FILE_or_FILES

Deleting a file

svn delete FILE_or_FILES

Reverting to a prior point in history

Sometimes you want to use the older version of a file because 'bad' changes got introduced to the repository. Say you have a binary pdf file, and you want to make an older version the current version. You do a merge, with a reversed merge range. This same procedure works equally well on text files.

First, look up file revision information:

svn log membership_agreement_print_version.pdf

Then, look up the merge command syntax and do a dry run before trying the real merge:

svn help merge
svn merge --dry-run -r 101:1 somefile.php
svn merge -r 101:1 somefile.php

NB To revert a whole tree, you would use 'checkout' with a revision number or label and that would get you the snapshot you wanted.

Renaming a file

If you have a file in subversion, and you wish to preserve it's history, but you want to rename it, use the svn mv command:

svn mv file:///var/svn/myrepo/www.example.com/trunk/images/smile.png \
file:///var/svn/myrepo/www.example.com/trunk/images/smile1.png

Deleting untracked files

Say your project spews build artifacts into your source tree, and doesn't clean up after itself. How do you clean out your working copy without having to do a clean checkout?

svn status -no-ignore | grep -e ^\? -e ^I | awk '{ print $2 }' | xargs --no-run-if-empty rm -r

Last Week's svn Log

svn -vr {$(date --iso-8601 --date="last week")}:HEAD log http://code.example.com/svn/project/trunk/

Add a bunch of new files

svn status . | grep '^?' | sed  's/^? */svn  add "/g' | sed 's/$/"/g' | sh

Find in svn

Old versions of Subversion would store metadata throughout the working copy, and offers no facility for searching the content. While you could and should setup a fantastic indexing service, you

find . -name \.svn/ -prune -o -name '*.php' -exec grep -l needle {} \; | sed 's/^/# /'