Managing papers with Subversion

by Willie Wong

Jumping through a link from Terry’s blog, I came across this article on the Secret Blogging Seminar describing how to use Subversion to keep track of one’s papers. (Better yet, this can also be implemented for collaboration.) This is one of those ideas that upon hearing, I slapped my forehead and went “why didn’t I think of it?”

In the past several months (after moving to my current position), I’ve just used rsync to download the files from the department server to my laptop before I start work, and to upload the changes afterward. This carries with it a slight headache: if I made some changes on the work computer, and if I bring my laptop to a coffeeshop with no wireless signals, I am in somewhat of a bind. I will have to edit my file, and be very careful that once I get internet access to merge the new version on my laptop against the version at work so all the changes are kept. With svn, I can look forward now to intelligent merging of the files automatically.

Subversion is what is known as a revision control system. It was developed in the land of computer science for manage computer code, especially across collaboration. The program makes it easy to keep track of revisions of a file: it knows which version is current and what changed between it and the previous versions. So instead of having to number each version of a file by hand and keeping track of the numbers, the computer does it for you. This reduces clutter in the workspace and minimizes the chance of mistakes. Furthermore, as we all know computer code tends to contain bugs (to err is human). With a system like this in place it is much easier to correct boneheaded mistakes: one just needs to revert to a previous version. The full documentation by the system of the changes made to the files also makes it easy to track down where and when a mistake happened.

A side benefit of subversion is that the files can be reliably merged across two separate working copies. This allows me to keep a central copy of my papers on the department server, and synchronize any changes between there, my laptop at home, and any other computer I may choose to use.

There are very many different ways of using subversion. Here I’m only going to describe the way I use it. (Just took about 20 minutes for me to read the relevant documentation and implement it.) Here I assume the user has

  • A personal computer running linux, with svn-client software installed.
  • Access (via ssh) to a server running linux/unix, with svn software installed.

Quick set-up instructions:

  1. First we need to create a repository. A repository is a directory where all the version information will be held. Log into the server via ssh (or if you have local access, just log in). Let us just give the repository a generic name, say, “WorkSVN”. Issue
      svnadmin create ~/WorkSVN
    This will create the repository under your home directory.
  2. Next we need to create a project. A project is a directory in which you hold a collection of files you want the svn system to keep track of. Suppose you already have a bunch of TeX files sitting in a directory called “PaperDrafts” under your home directory. We’ll just import the entire directory as your project
      svn import ~/PaperDrafts file:///[PATH TO HOME DIRECTORY]/WorkSVN/PaperDrafts
    Notice that inside the URL line, one cannot use the tilde-expansion for home directories. To find out the path to home directory, you can “cd” to the home directory, and issue
      pwd
    This should return a path like
      /home/XXYY
    Then the URL in the command above should be
      file:///home/XXYY/WorkSVN/PaperDrafts
  3. If you want a local working copy of the files, you can now first remove the PaperDrafts, and “download” it from the svn server.
      mv PaperDrafts PaperDrafts.bkup
    svn co file:///home/XXYY/WorkSVN/PaperDrafts ~/PaperDrafts

    The first command moves your old copy out of the way. The second command downloads, from the subversion system, all the files in the project you just created. Now double check all the files are there! Then you can clean up the back up copy with
      rm -rf PaperDrafts.bkup
  4. Now, to get a copy of the files on your laptop, we have to download it from svn. Suppose your server has a server name “Unseen.uni.am“. (This should be the same name you used to ssh.) Then just go to your computer, make sure you don’t already have a folder named PaperDrafts, and issue
      svn co svn+ssh://XXYY@Unseen.uni.am/home/XXYY/WorkSVN/PaperDrafts ~/PaperDrafts
    where the “XXYY” before the @ symbol is taken to mean the username you used to log into your server. The “/home/XXYY” after the server name is the path to your home directory on the server. Now after entering your password, you should have a copy of the papers!

To download the files to any other computer, just repeat the last step above.

Now, suppose you made some edits, what do you do? The principal commands to know are “add, del, copy, move, update, commit”.

  • If a file is modified in place, then you don’t need to do anything special: svn already know to keep track of the file.
  • del, copy, move: to remove, copy, or move/rename files inside the working directory, one needs to use the svn tools instead of the native linux tools. This is so that the svn system knows that the files are to be changed. So to remove a file, issue
      svn del [path to file]
    to copy a file,
      svn copy [path from] [path to]
    and similarly for move.
  • If you create a new file or directory, you need to let svn know that this file/directory needs to be kept track of. So you issue
      svn add [path to file/directory]
  • When you’ve done all the edits you want. You need to synchronize the local copy with the server. To do so just issue
      svn commit ~/PaperDrafts
    and any changes (deletions, copies/moves, new files, modified files) will be propagated to your server.
  • If you now go to another computer onto which you’ve already downloaded the TeX files before and want to update it to reflect any changes you’ve made since, you can issue
      svn update ~/PaperDrafts

Lastly, for commits and adds and deletes, it is often prudent to use the “-m” flag to svn to add a comment about what is being done and why you are doing it. Just in case you will look at it later.

The usage described here is very simple and primitive. For more complex operations, read the documentation for Subversion. It is available on its website.

About these ads