Subversion is a powerful advancement on the CVS program, popular for many projects. This document covers the history, the theory and practical examples of how to use Subversion to manage changes and releases of software products.
What is Subversion?
Subversion is a revision control system, typically deployed as a source control management system. Subversion supports access to repositories via HTTP/HTTPS, SSH and a native SVN protocol. Subversion builds on previous revision control systems (such as the original RCS and CVS) to provide a feature rich system for storing revisions.
Subversion is presently a rather mature product and is being offered by large open source repository systems in place of previously CVS based repositories. Examples of this are SourceForge, Google Project Hosting and JoomlaCode.
Alternatives to Subversion
Historically CVS has been the dominant open source version control management system but it has had its failing and is now being less commonly used. Other version control options available are:
* Monotone (Wikipedia)
Monotone follows a similar design to Git, Mercurial or Archs in providing distributed version control. A strong advantage is the more 'peer to peer' approach where each client can act as a 'server' as opposed to Subversion's more rigid approach. To support this Monotone uses certificates to validate commit identities to ensure author validity. Monotone however doesn't have as much GUI support (e.g. no tool such as TortoiseSVN) and isn't as mature a product. For highly distributed development environments where authentication is important, Monotone would be preferable.
Git was developed by Linus for kernel usage after a fallout with the previous kernel SCM 'Bitkeeper'. Linus wanted something that didn't take the traditional approach to version control and in some ways this makes it more difficult (and CPU intensive) than other alternatives. Where SVN is strongly client-server, Git is aimed strongly at being in a heavily distributed environment. Of a similar design, purpose and origin to Git is [http://en.wikipedia.org/wiki/Mercurial_%28software%29 Mercurial].
SVK is an offshoot and extension of 'SVN' allowing for easy distribution such as the case of the other mentioned SCM's. SVK adds such abilities as offline operations (e.g. offline commit), mirroring and distributed branching. As with the rest, this product is aimed more at distributed development as opposed to a more centralized development model or development with a small set of contributors.
Wikipedia has a list of revision control software as well as a more in depth comparison.
Getting started with Subversion
One of the greatest advantages of Subversions is the ubiquity with which Subversion client software is available. Interfaces exist for web based management (Insurrection) and access (builtin), GUI access (eSVN, svnx), integrated file browser access (TortoiseSVN) and command line access (builtin). This means that there are a number of options available to use without running into great issues with compatibility.
Subversion command line
By default the subversion client is command line based. This means that for any command line orientated system (particularly Unix based systems), most administrators will feel at home. This however isn't the only option as there are many clients available (both free and nonfree) to manage the client side of the Subversion repository. The command line client completes all tasks that the graphical clients can.
eSVN is a KDE based SVN client running primarily on Linux. eSVN supports 'workspaces' which manage multiple Subversion locations in a central environment. eSVN follows a similar methodology as Cervisia, the KDE CVS client, but extends the idea by controlling multiple working directories in one workspace.
svnX is a Mac SVN client that is basically a simple front end to the command line client. While it doesn't provide too many advanced features, it provides a simple GUI to manage commits, checkouts and multiple repositories and working directories.
TortoiseSVN is a Windows Explorer integrated client that allows a user to commit and checkout repositories directly from Windows Explorer. TortoiseSVN also has an integrated 'Repobrowser' that allows simple remote operations to be completed on Subversion repositories (e.g. adding or deleting folders). TortoiseSVN also powerfully enables much more rapid views of the file system by providing 'overlays' on top of the file/folder icons allowing a user to instantly see which files are up to date, in conflict, altered, new or unversioned. A similar tool exists for Mac OS X called SCPlugin that provides a similar function with reduced user friendliness and capabilities. Nautilus (GNOME/Linux) has available some scripts to make committing to repositories from folders easier but has no overlays (unlike TortoiseSVN or SCPlugin).
Subversion provides a basic HTML page in a similar fashion to the Apache DirectoryIndex directive, except more reduced again. This allows a user to slowly navigate around and download files with a traditional HTTP capable web browser.
Subversion provides an advanced WebDAV extension for Apache that allows tools such as Microsoft Web Folders, Mac OS X or cadaver (Linux command line DAV client) to manipulate the repository. This works in two modes: a read only and write capable mode. The default read only mode allows all of these 'basic' tools read access to the repository. They can complete copy operations and navigate it liek a normal folder. The second mode allows these clients write access. For each write to the DAV 'filesystem', a SVN commit is made to the repository. WebDAV is an extension of the HTTP protocol. For clients that understand Subverion's advanced WebDAV implementation (e.g. most Subversion clients), WebDAV/HTTP/HTTPS can be used as another commit source the same as using SVN+SSH or the pure SVNSERVE protocol.
Insurrection isn't actually a client in itself but provides are better interface to the normal HTTP output generated by Subversion. In additional to providing some nicer features to the standard HTTP front end, it also allows remote repository creation and management. It can create and edit repositories as well as editing a users access to the repository.
Subversion Repository Layout Theory
Subversion, with its history based on CVS, approached many things that people felt CVS did badly differently to achieve different goals. This has meant that a different approach to things has been taken to allow for certain tasks that were difficult under CVS (like renaming a file) to be easier under SVN. However one of the tasks made less clear was branching, which means that repository layout with Subversion is perhaps more important than CVS. The basic structure of a SVN repository is as follows:
The trunk is where the main development occurs and where most commits occur. Trunk is always the most up to date and is used to provide the next release. From trunk a version will typically be tagged and places into release.
Once a version of 'trunk' is said to be released, the entire trunk folder is copied into releases for that version (say 1.0). Trunk continues incrementing major version (e.g. 1.1) so that bug fixes and security fixes can be applied to the releases folder copy. From here the security or bug fix releases (perhaps even features) can be moved into tags to account for tracking of these (e.g. 1.0.1, 1.0.2).
Tags is typically a static (e.g. no changes after commit) location that holds each version. A typical tags directory may look like this:
This means that a given version can be located by simply checking out the appropriate folder. This makes version rollbacks easy (svn force export a previous version) as well as moving forwards (export the new version over the top of the old version).
Sometimes there are large changes to the code base that might have an impact on the other developers working on the project. In this case we have branches to work on making this wide scale changes in an environment that won't impact on the rest of the repository. Because SVN has more limited support for branching, this makes merging changes back in a bit harder, however not impossible. Additionally some use a secondary branches folder for individual releases (e.g. 1.0 branch) for times when there are serious changes in the stable release.
Subversion is a version control system, which means that it is implicitly implied that it handles changes within files. However since it is well suited to handling changes in files it can be used for configuration change management and examining alterations in configuration files (typically the Unix world where configuration is contained in a file as opposed to the Windows model which relies primarily on a registry). A good example of this could be the Apache directories on a web server. If these are managed by SVN we can see what changes are being made (e.g. by Webmin) to allow for rollback of settings to a last known good configuration in case of corruption of settings. Tomcat is another example of a server that utilizes file to control its configuration making it easy to version control these changes.
A core usage for SVN is to provide a basis for release management. As a product is developed in trunk it will eventually reach a point where development will stop on this and the product will be released into a more maintenance mode. Whilst development of new features in trunk can occur, it may not be desirable for these to be back ported to fix a bug (or vice versa, the bug may not actually exist in the later trunk version). So for example we have a product in trunk that we have been developing and now its time to release the product. The new release version number will be '1.0' with the next release being developed in trunk called '1.1'. The following actions would occur:
* The trunk is copied to the 'releases' directory with an entry with the appropriate major.minor version number (e.g. /releases/1.0)
* The trunk is copied to the 'tags' directory with an entry with the appropriate major.minor.revision version number (e.g. /tags/1.0.0; optionally revision may be ignored for 1.0 release)
Trunk is where the main development occurs and is continuously the most up to date version of the software.
Each folder contained here are under a 'maintenance' style mode where only bug fixes and security fixes are applied. Feature additions may be completed here but are typically left to the trunk branch. Since a folder here is separate to the main trunk, alterations can eb made without altering the course of the trunk or to address issues that may be a threat for the release (and hence necessitating a security fix/release) but not having an impact on trunk (e.g. that part of the code was refactored). From here branches are made for revision of the release (e.g. 1.0.1). As with trunk, a release is copied into 'tags' as well (e.g. the first security release would become /tags/1.0.1) so that in future that release can be grabbed quickly and easily.
Tags is the version store for every release. Ordered by version number, this is the final uneditable location of each release. Using this location as a reference, external releases can be quickly migrated forwards or back as the tags holds the changes for each release. After a release has been added to this directory it should be considered read only. Any changes happen in the relevant release directory or in trunk.
Subversion has numerous concepts and behaviours that might not appear immediately obvious to the user.
When importing into a Subversion repository a folder, one must remember that the contents of the directory is actually being imported, not the directory itself, into the repository location specified. So consider:
SVN Repository URL: http://joomlacode.org/svn/tccprojects/
Local File system Path: C:\Documents and Settings\moffats\My Documents\Projects\projects-external\tccprojects
What is happening is that SVN will import the contents of the local file system path into the SVN repository URL. This means it is not relevant what the name of the local system path is as the folder name is ignored and only the contents copied. Unfortunately Subversion cannot import the folder and turn it into a working copy (though the feature is planned), so one must check the resource out to create the working copy. Unless a different target folder is specified, Subversion will attempt to checkout to a folder of the same name (e.g. tccprojects), so keep this in mind when importing directories.
Subversion Server Notes
Which server model?
Since Subversion offers a few models for security, here is a guide to the usage of Subversion servers for each situation.
Similar to pserver (for CVS), svnserve is a server process typically run from inetd and uses its own built in authentication source by default. This is useful as it allows a fully independent authentication model for the SVN repository that relies on no other sources to authenticate the user. This of course is a downfall as it becomes another login to maintain. Insurrection resolves this slightly by providing an easy administration tool but in reality for a corporate environment with pre-existing user data it is unsuitable.
This method is actually a wrapper for the above with user authentication and groups actually handled by the host system's SSH server (typically PAM). In this case a user must have physical access to the repository on the server (read-write file permissions granted by user ownership or group membership) as the system spawns a svnserve instance and transfers data over the SSH link. This is useful for a limited group of people committing to the repository who would normally have access to the servers anyway. Passwords can be linked via PAM to alternate authentication sources though it is highly suggested that SSH keys are implemented to ensure that the password dialogs aren't presented excessively. This is similar to using wrappers for CVS to access and edit repositories.
Apache is the best all round solution, especially for enterprise. Whilst users can be authenticated against the local SVN files, exactly the same as svnserve, Apache's more advanced authentication methods allow for a wider selection of authentication opportunities, such as LDAP. Additionally Apache offers SSL communication to allow encrypted links and a simple web based repository viewer that allows file downloads with a conventional web browser. This server model is perhaps the best when combined with an enterprise environment. User access control to repositories can be done using the same method employed by svnserve, and authentication may also be completed using the exact same files (in addition to methods Apache supports such as LDAP).