Subversion is used for revision control system

I have started using subversion, a concurrent version control system, to track written documents as well as source code (for more details on subversion then provided here click on this). The advantages of this approach are: Subversion performs "lockless" updates on documents, allowing multiple users to update the same document concurrently. If these updates are for non-overlapping parts of the text, they are assumed to be non-interfering, but true understanding of whether these updates interfere depends on deep semantics and can therefore be done only by humans.

To ensure that the everyone has the latest copy, one should update and commit often (see below), and one should coordinate with others that are working on the same project. Even if you don't, subversion ensures that no changes will be lost, but the procedure for resolving the conflicts are tedious--since each conflict needs to be examined and resolved.

You are assumed to have subversion, ssh, and python installed on your client. (Python is needed only if you run ssh-installkeys described below.)

The steps are:

  1. click here to get instructions to set up things on rites and your client.
  2. Checkout an existing project (needs to be done once per project)
  3. Edit and modify the project (can be repeated arbitrary number of times)
  4. Resolving conflicts--oops! (what happens if there are concurrent updates to the same part of the document).
  5. Tools to compare different latex versions

Checking out a project for the first time

You will first need to checkout the document, that is get a copy of the document which exists in the repository:
svn checkout svn+ssh://rites.uic.edu/home/svn/type/proj
Note: for deposits before August 2006, use: rites.uic.edu/home1/director/subversion/type/proj. Where type is one of papers, proposals, or source and proj is the particular project name, for example certificates. A directory with the name you typed for proj will be created under the current working directory.

Editing

The basic workflow for checked out files is described here. In consists of:
  1. updating: ensuring you have the latest copy
  2. the edit cycle: where you change your copy and
  3. commit: where you put your copy back into the repository
All the commands assume that you are working in the proj directory or some directory under it. Note that you can commit as often as you like, ensuring your changes are revisioned (so that you can undo at revision granularity) and making the changes visible to other authors. In general, when you commit a latex file should successfully be processed by latex, source code should successfully compile. (Actually, the requirements on source code depend on the stage of the project: early, you just check in notes; then later, the source code should parse; then later, the source code should link; and later on, the source code should pass a test suite.)

Updating

If you checked out this file a while ago, and/or someone may have made changes to it, you need to update it:
  • svn update

The edit cycle

You can now edit the files in the directory with the editor of your choice.

If you want to copy, move, add, or delete files or create a directory you need to type:

  • svn copy filename1 filename2
  • svn move filename1 filename2
  • svn add filename
  • svn delete filename
  • svn mkdir filename
You need to tell subversion about what you did with these files so that it includes it in its repository and tracks the changes. Note that subversion does not track all changes, only those that you tell it to.

The information kept in the repository for text are the .tex, .bib, the figure source (eg. x.dia) and the source converted to pdf (eg. x.pdf). The idea is that, using only pdflatex and bibtex you can modify and latex the files; you do not have to have the figure drawing package unless you want to modify the figures.

For source code, it is the source, documentation, and build software which is kept in the repository, although documentation may be kept externally.

Saving the results

It is best to save early and often. This is accomplished by:
  • svn commit
It will pop up an editor and ask you to write a (presumably short) comment about what you changed. Comments are often just a line or two, indicating what types of changes have been made to which files. (You can set the environment variable EDITOR to the name of your preferred editor).

If you want to see what changes have been made, type

  • svn log

Resolving conflicts

If you try to commit your document and someone else has committed a document since your last checkout/update, the commit will be refused. You'll need to do an update. If the changes you made and those made by the other person are near each other, than they will conflict and subversion will be unable to automatically resolve them. Assume that the conflict is on fullModel.tex.
  1. Then svn update will create files fullModel.tex.rN, fullModel.tex.rM for the two versions of the file, and perhaps fullModel.tex.mine if its different from fullModel.tex.
  2. fullModel.tex now contains some kind of "markers" indicating where the differences are.
  3. your choices are:
    1. edit fullModel.tex and resolve differences
    2. copy over one of fullModel.tex.r{M,N} fullModel.tex to keep one version of the changes and throw away others.
    3. type svn revert to throw away your changes.
    Undoubtedly, you want to do a) and find out what kind of editing marks are there. You might want to do a
    diff fullModel.tex.r{M,N}
    to have some idea of what they are and what to search for.
  4. when you are done resolving the changes, type
    svn resolved fullModel.tex
    (which removes fullModel.tex.{mine,rM,rN}).
  5. now you can commit

Tools to compare different latex versions

Subversion keeps track of a global version number for the repository. Hence, if there are multiple projects in the repository, the version number of a project can increase without any changes to the project.

We have been using latexdiff, with some success, to compare different versions of latex documents. Its not perfect, and its available from CTAN, but I've included a copy here.

To use it with subversion, I've hacked together a small script called svndiff available here. Install both scripts and make them executable.

To use it type

svndiff type proj date paper
where type and proj is as defined above, date is an svn revision name and paper is the name of the document without the trailing ".tex". For example:
svndiff papers securityProperty {2005-07-01\} paper
will take the securityProperty directory out of the papers repository as of July 1, 2005 and compare paper.tex in that directory vs. paper.tex in the current directory. It will produce a file called paper-diff.tex. Note that the "\"s are there to prevent csh/tcsh from using the braces as shell meta characters, your mileage may differ with other shells.