Excursus

Subversion, a free and open source version control system, is great for keep track of the development of your LaTeX documents. As cool as it is, though, it has its limitations. One serious limitation is branch management.

Suppose you have a document that you are writing and that you are considering restructuring that document. Suppose, further, you are unsure the restructuring will come off in the end. If the document is being kept in a subversion repository, then it is natural to create a branch. The trunk is the directory where the document in its main or current line of development is being kept. The branch is the directory where the alternaitive line of development is being kept. A minimal example of the directory structure would look like this:

|-- mylatexproject\
    |-- trunk\
        |-- mydocument.tex
    |-- branch\
        |-- mydocument.tex

(The diagram is in one way misleading—the trunk and branch directories can contain multiple files.) To create a branch, simply copy trunk\mydocument.tex into branch\ (using the subversion commands, so that subversion knows what’s happening).

If after restructuring your document, you are happy with the changes, then you merge these changes into the trunk. This is done with the command:

svn merge

This command does two things:

1. It compares the differences between two files
2. It applies the differences to a location in the working copy

The command thus takes three arguments. The first two arguments are the locations of the files to be compared (where these can be specified, for example, with their urls in the repository), and the path of the file in the working copy where these changes are to be applied. Notice that the changes are applied to a file in your working copy, so you will need to commit these changes after the merge. For more information see the subversion book or use the command:

svn help merge

Sounds easy. It is. But there are limitations to subversion’s merge command. Let me discuss two.

The first limitation becomes apparent when you repeatedly merge changes. It can happen that you merge the same change twice over. Sometimes this is not a problem. If subversion sees that the relevant file already has the relevant change then it does nothing. But suppose the change has been made but has been further modified. Merging a second time will produce a conflict. The problem arises because subversion doesn’t remember what changes have already been merged into the trunk and so attempts to merge these again.

The second limitation is the inability to exclude a previous revision form being merged. This is particularly relevant to writers. Suppose you are writing a paper and have been invited to give a talk based on that material. It is natural to create a branch. It is also natural to eliminate some things from the talk like footnotes. You do this and commit the change. But suppose in writing the talk you hit upon things that should be in the paper. Suppose commit these changes as well. You would now want to merge these changes into the paper, which is in the trunk. However, you cannot tell svn merge to merge only those changes, and to not merge the previous changes. So with svn merge you would end up losing the footnotes in the original paper.

It is partly for these reasons that Linus Torvalds regards subversion as broken by design. It is true that these problems do not arise in distributed models of version control such as Git and Mercurial.

Fortunately, for subversion users, these and related limiations are being addressed in the next major releas of subversion (1.5.0). But if you cannot wait until then, the script svnmerge.py can help. svnmerge.py is a tool for automatic branch management that addresses these problems. It remembers which changes have already been merged and does the right thing by only merging the new changes. And it lists changes available for merging so that some, but not all, of these can be merged. I have been playing around with svnmerge.py, and will post more about is use.