Saturday, December 30, 2006

Subversion for Document Management

I am going to use subversion and ssh for document management and off-site document storage. Subversion is a revision control system. It will allow me to work on the project from any computer since I can download the project files, work on them, and then upload the changes. Moreover, Subversion will keep track of the revisions, allowing me to revert to older versions if necessary. This post describes how to use subversion for document or small project management. See the work cycle section of the Subversion Book for a more detailed exposition. [I recommend using ssh-keys and ssh-agent on your main computer so you don't have to type your ssh password several times per session; see the post on creating and using ssh-keys.]

Setup. Install Subversion. Both on your client machines and on the server (ask your sysadmin). On Ubuntu:
apt-get install subversion
Below the subversion server will be called, and the username will be username. I ssh'd to and ran the following command to create a Subversion repository where Subversion will store the projects.
svnadmin create ~/subversion-repo
Create Project. To create a new project, create a new directory and populate the directory with files that you will need.
mkdir brilliant-paper
Import Project. Import the project into your subversion repository with the following command.
 svn import -m "My Brilliant Paper" brilliant-paper svn+ssh://

Now delete your project directory. (You will download a working copy in the next step.)
 rm -rf brilliant-paper/*
Work Cycle. The following steps describe how to use Subversion to work on the project.
  1. Download Project. Sit down at a computer, any computer, install Subversion if necessary, and download the latest version of the project. Either:
    • download the project, if is hasn't been downloaded before:
      svn checkout svn+ssh://

    • or update the project if you've already downloaded a version of the project: in the project directory run,
      svn update
  2. Make changes.
    • You can edit any files that exist and subversion will detect those changes.
    • If you want to add a new file, then use the add command.
      svn add newfile
    • Similarly, you can delete, copy and move files or directories.
      svn delete filename
      svn copy filename copyname
      svn move filename newname
  3. Examine Changes. Nothing above makes changes to the project in the repository. Before you commit any changes you might want to examine the changes you have made. Use the 'svn status' and 'svn diff' commands. If a file has changed and you want to revert to a previous version, then revert to the most recent version of that file in the repository with the command 'svn revert filename'.
  4. Commit Changes. Commit your changes with the commit command.
    svn commit -m 'Write a summary of your changes here.'
  5. Check Commit. In the top of your project directory run the status command.
    svn status
    If there is no output, then all changes have been committed. If there is some output, then there are files that have been changed or added, but not committed for some reason. See the help page to decode the output: svn help status