This title is about Subversion, an open-source, cross-platform version control system. The Subversion project arose out of frustration with the limitations of CVS (Concurrent Versions System), for years the de facto standard in the open source world and also widely used by commercial projects. Subversion is designed to be like CVS, but to fix its flaws. A key improvement in Subversion is atomic commits. This means that when you commit a changed project, either all the changes succeed or none, like a database transaction. In fact, the usual format for Subversion repositories is a database, using Berkeley DB, although recent versions can also use a repository type called FSFS, which is in effect the file system. Subversion also has easier and more efficient branching and tagging than CVS. Another great feature is integration with Apache 2, enabling Subversion to use Apache’s authentication and authorization feature as well as supporting WebDAV (Web-based Distributed Authoring and Versioning). You can browse a Subversion repository with any web browser, and mount a repository as a directory using WebBDAV clients, such as web folders in Windows. Network and Internet users also benefit from efficient differencing routines which reduce network traffic on updates and commits. Features like these have earned Subversion strong popularity and support.
This is more than just a book about Subversion. It has an intimate relationship with the project. Written by core members of the development team, the electronic version of the book is supplied with the Subversion downloads; it is really the official Subversion manual. In fact, the book itself is open source. However, if you decide to purchase a copy from O’Reilly you get the convenience of a printed copy as well as supporting the project in a small way. The online version will be more up-to-date, but personally I still find a printed reference easier to read; the choice is yours.
There is a downside to the book’s official status. It is tightly focussed on Subversion itself, and the only mention of third-party tools is a list of urls in an appendix, some of which appear to point to inactive projects. As a user, I would have liked some notes on the more important additional clients such as TortoiseSVN, a client for Windows which hooks into Explorer, as well as some information on how to use Subversion with popular IDEs such as Eclipse, JBuilder and Visual Studio. I understand why the authors considered this beyond the scope of this particular book, but it would help to make Subversion more accessible for newcomers.
What you get in the book
The authors recognize several distinct readership categories, and the book is designed around their different needs. The four categories are system administrators, new users, advanced users, and developers. Chapter one is a general introduction and overview of Subversion, following which are three chapters on how to use the Subversion client. These chapters are written from the user’s perspective. The second of them covers the basic work cycle, explaining in around 20 pages how a typical developer would use Subversion in the course of a day. The cycle includes retrieving the latest source from the server with the update command; adding and removing files from the repository with add and delete; reviewing your changes with the status command; examining them in detail with diff; backtracking with revert; merging changes with those made by others, and finally using commit. This section forms a kind of user’s mini-manual; it’s full of common-sense tips and shows how easy it is to get going with Subversion.
I also enjoyed the following chapter which covers branching and merging. This explains both the concepts and the best practice of working with branches and tags, as well as the mechanics of how to do it with Subversion. You can make liberal use of branches and tags with Subversion, because it makes what are called cheap copies. This means that copies are maintained as pointers to the original unless they are subsequently changed.
Next come two chapters aimed at administrators, which explain how to create and configure a Subversion repository. After that there is a chapter on advanced usage of the svn client, followed by a chapter aimed at those who want to understand how Subversion itself is developed and possibly get involved. The book closes with an all-important reference to the Subversion client and tools, and there are appendices covering Subversion for CVS users, troubleshooting, WebDAV issues, and the list of third-party tools mentioned above.
I understand why the book is laid out as it is, but I have a few quibbles. To me it would have been more logical to begin with server installation and configuration, and then move on to client usage, simply because you cannot do much with the client until the server is in place. I would also prefer to have the chapter on advanced topics, which mostly relates to the client, next to the other client-focused chapters. If like me you are trying Subversion for the first time, you will read the middle of the book first, followed by the early chapters, and finally skip to the end. It is a minor gripe as you soon find your way around.
The actual content is excellent. The book is written in short sections, with plenty of headings and sub-headings to break up the text. There are lots of examples and common-sense explanations, and the authors have a deep knowledge of their subject. Many open-source projects are poorly documented, so having this Subversion handbook is a big advantage.
Installing Subversion
This book was timely for me as I had been meaning to try Subversion for some time. Guided by the book along with online resources, I created two Subversion installations, one on Windows 2003 and the other on SUSE Linux 9.0. The Windows server already runs Microsoft Exchange and Internet Information Server (IIS); it is not a production server, but used for testing and development. I downloaded and ran the Windows binary installs for both Subversion and Apache 2. The only problem I had concerned Apache integration. Apache will co-exist happily with other web servers such as IIS or earlier versions of Apache, provided that it listens on a different port. This can be amended simply by changing the LISTEN directive in the Apache configuration file. Subversion integrates with Apache through two modules, mod_dav and mod_dav_svn. However, my first efforts to load the Subversion module failed, and Apache would not start. The event log reported that the module could not be found, though what it really meant was that one of the module’s dependencies was not found. I fixed the problem by copying libdb42.dll and libeay32.dll from the Subversion/bin directory to the Apache modules directory. That is OK for testing, but it is not ideal since I will have to remember to re-copy the libraries when Subversion is updated, so sorting this out properly is on my to-do list. Aside from that, the Windows installation was straightforward and I was soon up and running creating a repository and configuring Apache to serve it to my intranet.
Next I turned to Linux. I decided again to use a binary download, and followed the links from the Subversion download page to the SUSE downloads. Installation was reasonably straightforward, though the package manager reported two dependencies, SWIG, the Simplified Wrapper and Interface Generator, and Neon, an HTTP and WebDAV client library. Once these were in place I created a repository and configured Apache. It was also necessary to give the Apache user read-write access to the repository directory. In my limited tests so far, the Linux installation behaved in an identical manner to the Windows installation. If you have a free choice, Linux is the natural home for Subversion, but it should slot easily into a Windows-based network as well.
Subversion components
There are several pieces to Subversion. The command-line client is called svn; this has the largest number of options and is the piece that developers using Subversion will use constantly. Svn can talk to a local repository addressed using a File URL, or to a repository located on the network. Network repositories are served in one of three ways. If you use Apache integration, you use an HTTP URL, for example:
svn checkout http://myserver/repos/myproject
An alternative to Apache is svnserve, a dedicated Subversion server which runs as a daemon and supports the svn protocol:
svn checkout svn://myserver/project1
Until recently, the File URL was only supported for repositories on the local hard drive. This is a requirement of Berkeley DB, and still applies if you use Berkeley to manage the repository. However, the new FSFS repository type can be used on a network share. It also enables repositories to be hosted on Windows 98, if you must.
Another key component is svnadmin, the tool for creating and repairing repositories. This tool should always be run on the machine where the repository is located. Two further tools are svnlook, which reports on the revisions present in a repository, and svnversion, which analyzes the state of a working copy. However, most of the time you will just use the svn client for day-to-day work, and svnadmin for administration.
Although it is a complex product, Subversion has a clean command-line syntax and typically developers will find it easy to use. If your chosen IDE has Subversion integration, you may be able to work mostly through that. However, although SVN plug-ins for leading IDEs are available and getting better, it does not yet come close to the wide support enjoyed by CVS. If IDE integration is important to you, that might be a reason to delay a move to Subversion. On the other hand, there are advantages to working with Subversion outside any IDE, especially if you have something like TortoiseSVN which integrates so well with the shell. It avoids problems such as you get when using Visual Studio .NET with Visual SourceSafe (VSS), where it can be quite an effort to remove the VSS hooks from the project files. One of the nice things about Subversion is that it doesn’t get in the way of your source code. All the metadata for your working copy is isolated in a separate subdirectory called .svn. Note to Windows uses: the dot prefix means this is normally a hidden directory. On Windows it also has the hidden attribute set, but there’s a story here. If you have Subversion IDE integration in Visual Studio, the dot prefix causes problems. The rather ugly and unofficial solution is to do a special build of Subversion that uses an underline prefix instead. Let’s hope this is all fixed in the forthcoming 2005 release of Visual Studio.
The Subversion philosophy
Early in Version Control with Subversion the authors explain the basic concepts behind the product. In essence, Subversion uses the concept of a centralized repository to which all users connect. Unlike some other systems, Subversion does not allow users to lock files they are working on. Instead, it allows multiple users to work on a file, and reports on any conflicts. When there is a conflict, Subversion inserts conflict markers into the affected file, showing the incompatible edits, as well as making local copies of both your original and the conflicting server version. You can resolve the conflict in any editor, or use a merge tool. Incidentally, locking support is intended to appear in a future update to Subversion, although there are good reasons to prefer Copy – Modify – Merge, as the book calls it, in most circumstances.
There are other ways to manage source code. One of the most interesting is well represented by GNU Arch, which uses a decentralized model. This means every user has their own repository, and edits from any repository can be copied or merged to any other. Switching to a new version control system is not trivial, and it’s worth thinking through which model suits you best before committing yourself. A possible problem with Arch itself is its poor Win32 support; Subversion is much better in this respect.
Last words
For anyone considering Subversion, this book is a great place to start. It is manageable in length, well-written, and detailed without ever being tedious. I would recommend that you also check out third-party Subversion clients, and work out how you will use Subversion alongside your preferred IDE or editor. If you are already using Subversion, then the book is most likely already sitting on your hard drive. A hard copy is still worth considering, but what really counts is that this superb source code management system also has high quality documentation.
Links
Version Control with Subversion at Amazon.com
Version Contron with Subversion at Amazon.co.uk
Copyright Tim Anderson 1st November 2004. All rights reserved.