Multiuser Subversion
Pages: 1, 2

Metadata

An interesting feature of Subversion is that it allows an arbitrary amount of metadata to be attached to any versioned resource (files and directories). Metadata, like files, are also versioned. This metadata is a set of key/value pairs, known as properties.

You can use properties to annotate files (let's say, review-status to this file is being reviewed by Joe), or directories. For example, on a tag directory frobnizer-1.09b, you can add a note beta release, for internal use only.

Properties whose names begin with svn: are reserved by Subversion. Some of them are specifically recognized and handled. For example, svn:executable marks a file to be checked-out with the executable flag set on filesystems that support it. Other interesting properties include:

• svn:keywords controls keyword expansion. Like CVS, Subversion can replace strings of the form $Keyword$ or $Keyword:...$ embedded in text files. The keywords that you want to be replaced should be listed in the value of the svn:keywords property. Subversion provides keywords for the last user that modified the file, the last revision number that affected the file, the date of this last revision, and an absolute URL for the file in the repository. For example, if the standard headers for some of your files contain the keywords $Rev$ and $Author$ , you can enable their automatic substitution with the following commands:

  $ svn propset svn:keywords 'Rev Author' *.c
  $ svn commit -m "Enable keywords Rev and Author on C files" *.c

• svn:mime-type attaches a MIME type to a file to be used when delivering the file via HTTP. It's also used to determine whether the file should be stored internally as text or as binary. No MIME type, or a MIME type that begins with text/, indicates a text file. All other types indicate a binary file. Note that the svn import and svn add commands try to recognize binary files and tag them as such, with the default MIME type application/octet-stream. Subversion does not attempt to make diffs between different versions of a binary file.

• svn:eol-style is very useful when several developers work on different platforms. It's used to force the line endings to CR, LF, or CRLF, or to check-out always the file using the native line ending used on the developer's platform.

Branches, Switching and Merging

I presented an overview of tags and branches in the first article. Branches prove to be useful mainly on multiuser projects. With branches, a developer or a team of developers, can work on an experimental feature without interfering with the main development. Branches can also be used to keep track of changes in a maintenance version of a product. They can be used to handle beta releases and the returns of beta-testers. Subversion makes it easy and cheap to create branches, so why shouldn't you use them?

A branch is typically created outside a working copy to spare disk space with the form of the copy command that operates directly on URLs. The following creates a maintenance branch from the current project trunk (by convention, the root directory of your project files):

$ svn copy http://my.host/svn/frobnizer/trunk \
	http://my.host/svn/frobnizer/maint-1.0

To start working on a branch, you can of course check out a whole new working copy corresponding to it, but it's easier to switch your working copy (or parts of it) to the branch. Assuming that your working copy already contains the trunk, you can make it point at the maint-1.0 branch with the following command, issued at the root of your working copy:

$ svn switch http://my.host/svn/frobnizer/maint-1.0 .

svn switch works a bit like update, except that it doesn't conceptually move your working copy through time (revisions), but through space (branches). Consistently, the output of switch is similar to that of update.

Finally, to integrate changes from another branch in your working copy, you can use the powerful svn merge command. merge can be compared to diff, but instead of outputting changes as a unified diff to standard output, it applies them to your working copy (as you would apply a patch).

For example, the following commands integrate a batch of changes from the trunk into your maintenance working copy:

$ svn merge -r149:155 http://my.host/svn/frobnizer/trunk
U  foo.c
U  foo.h
A  bar.c

$ svn status
M      foo.c
M      foo.h
A  +   bar.c

$ svn commit -m 'Integrate revisions 150 to 155 from the trunk'

The output of svn merge indicates which files have been affected by the changes, just like svn update. The svn status command reports the status of files in your working copy. In this exmaple, foo.c and foo.h have local modifications, and bar.c is scheduled for addition in the next commit. The + sign in the status line indicates that Subversion knows that this file has been branched from elsewhere, and will retain this information when committing it.

Note that you may have to resolve manually potential conflicts between the merge and the commit.

An interesting use of merge is to fetch changes from the current branch. This way you can roll back a change. The following command applies the changes of revision 200 to your working copy, in reverse:

$ svn merge -r200:199 .

Meanwhile, in the Real World

Once you're getting used to Subversion, you'll find that it can help you in ways you didn't expect.

A first example would be dealing with runtime configuration files during upgrades. Working on a software project where some global configuration variables (IP addresses, environment variables or trace levels) are read in a file, I have to modify this file almost every time the application is installed on another machine. A default configuration file is provided with the sources, and it's kept under version control because the set of configuration variables changes over versions. What to do when I want to upgrade a snapshot installed on a test machine, but without losing the local changes to the config file?

The solution is simple. Instead of installing the application on the test machine from a source tarball, I copied my statically linked svn client there and performed a check-out. Then, I adjusted the configuration files to my needs, without commiting the changes. Upgrading the software to another development snapshot is as easy as an svn update followed by a make all . The update process integrates the common changes to the configuration file (e.g., new variables) with the local changes (e.g., user/password to access a local database). This can be applied to any evolving configuration file you need to deploy: an /etc/profile, a .vimrc, or an httpd.conf.

Branches can also be used in creative ways. I work on an intranet application that ships with several sets of style sheets. For example, some are designed for low resolution screens and provide different font sizes and background images.

I set up two directories, /html/css/800 and /html/css/1024, to hold those CSS. The 1024 directory, for style sheets adapted to a higher screen resolution, is a branch of the other. When a CSS is augmented or modified, it's easy to incorporate its changes into the other branch while leaving the specific font or image settings untouched.

I'm sure Subversion will be used in ways its designers didn't imagine. That's what makes the success of a tool.

Hints and Links

• The Subversion home page. You can get from there the latest version of the Subversion Book, which is still being written.
• The Apache Software Foundation.
• Sleepycat Software, which provides the Berkeley DB.
• The WebDAV protocol. Subversion uses a subset of the WebDAV and DeltaV protocols, DeltaV being an extension to WebDAV, that adds versioning capabilities to it.

Thanks to Karl Fogel for having kindly reviewed this article.

Rafael Garcia-Suarez is a French software engineer and Unix system administrator.

---

Return to the Apache DevCenter.

How do you use Subversion?
You must be logged in to the O'Reilly Network to post a talkback.

Showing messages 1 through 12 of 12.

• Troubles setting up Subversion
  2004-12-06 09:53:05  projxpert [Reply | View]
  
  
  If you're having troubles setting up Subversion and your team wants to just focus on developing.
  
  We offer multi-user free, commercial & open source Subversion hosting solutions.
  
  www.ProjXpert.com -- Subversion Hosting and Issue Tracking

• New Subversion Community Websites
  2004-06-16 10:40:33  AForgue [Reply | View]
  
  
  Two new Subversion related community websites have just recently opened up. These may serve as a good resource for anyone looking for help with Subversion:
  Subversion Forums: http://www.svnforum.org
  Subversion Wiki: http://www.subversionary.org

• New Subversion Community Websites
  2004-06-16 10:39:49  AForgue [Reply | View]
  
  
  Two new Subversion related community websites have just recently opened up. These may serve as a good resource for anyone looking for help with Subversion:
  Subversion Forums: http://www.svnforum.org
  Subversion Wiki: mod_dav_svn NOT installed
  2003-11-14 11:01:17  anonymous2 [Reply | View]
  
  

  I installed using the FreeBSD ports system and the mod_dav_svn was not correctly installed. I can't find mod_dav_svn on my system at all. I'm not sure what to do from this point.
• mod_dav_svn NOT installed
  2003-11-14 11:11:32  chromatic | [Reply | View]
  
  
  I believe mod_dav_svn installs only if you have Apache 2 installed. Are you building a server or a client?
• mod_dav_svn NOT installed
  2004-08-31 09:43:37  svnguy [Reply | View]
  
  
  I'm having the same problem, I installed from fink. There is a mod_dav and a mod_dav_fs, but no mod_dav_svn
  
  
• mod_dav_svn NOT installed
  2003-11-14 14:56:45  anonymous2 [Reply | View]
  
  
  Building a Server and Apache 2 is installed and working, except when I try to engage the DAV SVN line in httpd.conf. Then it blows up, cuz mod_dav_svn.so doesn't even exist on my system.

• hui.. it works
  2003-01-14 10:13:10  anonymous2 [Reply | View]
  
  
  you MUST take the special versions:
  wget http://subversion.tigris.org/files/documents/15/2610/subversion-r4276.tar.gz
  wget http://subversion.tigris.org/files/documents/15/2609/httpd-2.0.44-dev.tar.gz
  wget http://www.sleepycat.com/update/snapshot/db-4.0.14.tar.gz
  that worked for me...

• tired of getting it up...
  2003-01-09 09:32:02  anonymous2 [Reply | View]
  
  
  cvs is definitly easyier to setup... if one could compile that subversion thing...

• Tried getting it up and running ...
  2002-12-21 08:54:49  anonymous2 [Reply | View]
  
  
  You found CVS to be easier to set up than Apache and svn ???!! You must be real masochist.
  
  Have fun with your cvs nightmare (trust me it is waiting to happen) ...

• I tried getting it up and running..
  2002-12-21 07:18:48  anonymous2 [Reply | View]
  
  
  ..and frankly just got frustrated at the newness of the various pieces required. Apache 2, the toolkit, everything else -- I just couldn't get it to work on a RedHat 8 system so I ended up with CVS.
  
  I like the way Subversion looks and hope that install documentation comes along for folks who might be programmers but not Linux geniuses. (I am no Linux genius. =))
  
  Thanks for the article.

• I use it for Java projects
  2002-12-20 08:51:29  anonymous2 [Reply | View]
  
  
  I have been using Subversion since it first reached alpha. I use it primarily for my open-source Java projects, most popular of which is JSwat. You can see the repository at my website: http://www.bluemarsh.com/repos/
  
  thanks
  
  nathan