Advanced document editing with Subversion version control

A Revision Control System (RCS, or: Version Control System – VCS) like Subversion archives versions of your project’s file(s) and restores them on demand, you can track differences, etc. – one may know such a system from the articles at Wikipedia for example. Version control is an essential feature of serious programming, but Subversion could also be employed for the publishing systems which are based on a non-binary, plain text working document such as TeX/LaTeX, Groff, the ones using the Open Document Format (OpenOffice.org Writer and others), etc.

Instead of storing locally, Subversion and the others can also interact with remote server based repositories which is the key to well organised collaborative development – several clients receive their copy of the current version from and submit their changes back to the same server (for this the forerunner of Subversion coined the whole branch of software “Concurrent Versions System” -  CVS). Such a configuration is ideal for employing a general BibTeX database or such things in research groups. Even for a single user an external server based configuration could be pretty useful when working on the same project on different machines, for always keeping a remote backup, etc.

To start with that, a simple local Subversion repository could be setted up in a minute on your Linux machine, and furthermore there are even some LaTeX packets for the collaboration with Subversion. I would like to give a little crash course here for that, next to some pointers to plugins and an outlook to the higher developed distributed systems (if you are interested in the multi user aspect). Everything also runs more or less the same way on Mac OS X and also on Windows.

Working with a local Subversion repository

When it’s not already installed on your system first you have to get Subversion from your packet repository the usual way, of course: on Debian or Ubuntu you’ll get it through apt-get install subversion (it won’t take much time, the software is quite lean). After that there will be the main program svn and some others available on the command line then. To set up a local Subversion repository you first have to pick a suitable place for it, a hidden directory like $HOME/.svnrep or something like that I would say would do well. With: svnadmin create $HOME/.svnrep the repository will be created, after that you’ll see several items in that directory you don’t have to care about: conf, db, format etc. (that’s a Berkeley Database which runs here).

Now, supposed you are in the project’s working directory containing the file myproject.txt or something like this, the whole content is saved to repository with: svn import ./ file:///$HOME/.svnrep -m ‘any comment’ (there always has to be a comment for import and commit, if no -m is given an editor opens). After that you can delete all the directory’s content (in this case myproject.txt; or – if you don’t want to do this – you could move it to /tmp/). Then do a: svn checkout file:///$HOME/.svnrep ./ and myproject.txt appears again, ejected from the repository (together with some administrative files in the hidden subdirectory .svn). The project resp. the directory now has been Subversion-ed. You can check the project’s status with: svn info in the working directory, it will tell what’s the associated repository, the current revision number, etc. svn list –verbose file:///$HOME/.svnrep gives you information what the repository actually contains.

If you want Subversion to handle several projects you could use subdirectories within the same tree: .svnrep/project1, .svnrep/project2, etc. Newly created files in the working directory are marked to be taken into the repository with: svn add filename – it’s useful to be able to specify which files in the working directory are going to be in the repository because when working with LaTeX for example the leading .tex file needs to be committed, but it’s pointless to do that also with the temporal files (.log, .aux, etc. – clean it up before you import the directory, try latexmk -c), or even with the resulting .dvi or .pdf.

When you modify myproject.txt, svn diff myproject.txt shows you the differences between the version in the repository and the new one in the working directory (there are several options for diff, please check the manpage). Whenever you have the feel that the next status of your project worth keeping is reached and it is the right time to save the current version to the repository, just do: svn commit -m ‘any comment’ and that’s it (in the language of VCSs the commit is called “checkin”). In the case you want to recover the last version you can always delete the working files and “checkout” again. There is much more possible, for example you could restore any of the previous versions and also specific files if you’ve exidentially deleted anything, but that’s basically it – if you’ve mastered this, you’re in.

LaTeX and Subversion

Generally, Subversion is able to stamp selected files with several metadata tags, which is very convenient. If the file myproject.txt for example contains the elements $Revision$, $HeadURL$, $Date$, and $Id$ in the header for example, and you give a: svn propset svn:keyword ‘Revision HeadURL Date Id’ myproject.txt, after the next commit the file myproject.txt will carry the revision number at the same place, the path to the repository, date and time of last checkin, and a compression of the other tags (for what was $Id$; this feature is called “keyword substitution”).

There are a few LaTeX packets which are able to evaluate these tags, svn, svninfo, and svn-multi for multi file documents (to be used alternatively; all are part of texlive-latex-extra). With these it’s possible to put a Subversion metatag like $Id$ into a footnote or the document’s header next to having it expanded in the source file’s preamble – with svn for example something like it goes like this:

1
2
3
4
5
6
7
8
9
10
11
12

\documentclass{scrartcl}
 
\usepackage{svn}
\SVN $Id$
 
\usepackage{scrpage2}
\pagestyle{scrheadings}
\chead{\SVNId}
 
\begin{document}
Hello world!
\end{document}

(the document class scrartcl and scrpage2 belong to the koma-script packet). Something like this is pretty useful to make sure what version you are actually proofreading. The tags will be updated automatically with every checkin. Another VCS support for TeX is Stephan Henning’s vc. It can deal with Subversion next to other systems like Git (see below), is also capable to handle multi file documents and runs even with PlainTeX (for the use with ConTeXt see here).

Plugins

Since the VCSs are very popular there are dozens of helpers, GUI frontends and plugins to improve the workflow, for automation of checkout and commit, for enhanced diff-ing, for displaying the repository, tracking revisions, helping with administrational tasks etc. (see for example the article on Subversion clients at Wikipedia). To pick out just a few of them, with a view to popular Linux applications:

• Since the editor Emacs has become the real “eierlegende Wollmilchsau” (recently Manuel Batsching posted on Emacs on his blog) it’s clear that there are also several scripts for dealing with Subversion: see the EmacsWiki, XSteve’s page, GNU VC etc. etc.
• For Vim there is the vcscommand and cvsmenu
• The ultra versatile development platform Eclipse (when you start with that you will never need another hobby) has several plugins to deal with several VCSs, Subclipse and Subversive are two of the available Subversion clients
• For the KDE file manager Konqueror there is the Subversion integration KSvn
• A dollop for OS X users: the very fine, price winning editor TextMate also features a plugin for the collaboration with Subversion, see here.

Revision control beyond CVS

Common VCSs like CVS and Subversion which a running a centralized server architecture have some limitations: overlapping commits always evoke a conflict which has to be resolved manually, proper commit access control is a problem, just to name a few. Higher developed applications like Mercurial or Git are employing a noncentralized model for overcoming them, for that they are designated as Distributed Revision Control Systems (DRCS). Since there commits and even branching can be done without being connected (here not commit actually saves to the server but push) there are benefits for offline work. That also means that in collaborative development you could employ the same version control for your own drafts you don’t want to publish, and many other things. But the advantages of these systems go even deeper so that they should be chosen instead of the common ones especially for multi user projects. If interested in these fascinating matters please follow the last pointers on the list of references:

References (systematically):

• O. Frommel: Veränderungen festhalten – Prinzipien der Versionskontrolle erklärt. In: Linux User 5/2006, 60-61.
• J. Plötner/S. Wendzel: Ordentliche Buchführung – mit CVS oder Subversion Quelltext verwalten. In: Linux User 10/2006, 84-87.
• K. Azad:A visual guide to version control @ Betterexplained.com
• B. Collins-Sussman/B.W. Fitzpatrick/C.M. Pilato: Version Control with Subversion.
• D. Berlin/G. Rooney: Practical Subversion. 2nd edition. Berkeley: Apress 2009. ISBN 978-1-59059-753-8.
• C. Sobaniec: Subversion quick reference card.
• A.Henningsen: Tools for collaborative writing of scientific LaTeX documents. In: PracTeX Journal 3/2007.
• E. Kalderon: LaTeX and Subversion. In: PracTeX Journal 3/2007.
• U. Ziegenhagen: LaTeX document management with Subversion. In: PracTeX Journal 3/2007.
• M. Scharrer: Version control of LaTeX documents with svn-multi. In: PracTeX Journal 3/2007.
• A. Shand/N. Gift: Introduction to distributed version control systems.
• J. Loeliger: Version control with Git. Beijing (etc.): O’Reilly 2009. ISBN 978-0-596-52012-0.
• Linus Torvalds on Git at Google Tech Talks, 05/03/2007
• K. Azad: Aha! moments when learning Git @ Betterexplained.com