SVN HOWTO

This document describes the methodology for using svn for developing webs software. Following this will result in an organized svn tree which is easy to follow.

Top-level Directories

• /code: for source code files. Most software and documentation lives here, and so there is a special organizational scheme for this directory.
• /docs: documents such as papers and posters. If there are figures which can be generated directly from raw data, it is okay to check in the data and analysis scripts here.
• /data: data which is not attached to a particular document may be checked in here.

/code Guidelines

The goal of the the code/ directory is to have one subdirectory per project, such that anyone can checkout and build various versions of software projects. In general, the structure should be as follows:

 /code
    + /project1
             + /branches
             + /tags
             + /trunk

The trunk directory is the current development tree; the primary maintainer checks in day-to-day additions and feature additions here. It may not be stable.

The branches directory stories copies of trunk, which may have been made for several reasons

• the primary maintainer may wish to experiment with disruptive changes to the main code without effecting other users.
• other users may wish to pick a snapshot of trunk, and periodically merge changes from trunk into the branch. This has several advantages:
  • the user may check in changes which only he will see.
  • because he only occasionally merges with trunk, he is can be sure of what version of software he is using.
  • anyone can compile his application from exactly the same sources.

tags also stores copies the tree, but unlike branches and trunk, should never be committed to. The purpose is to save a snapshot for the future. For instance, creating a tag before a deployment will allow future users to reconstruct the software version used.

SVN One-liners

• Creating a branch-- the process is the same. In svn, this is a "lightweight" operation. Suppose the project is named 'foo', and we want to create a branch named 'mybranch' This command creates the tag; you'll still need to check it out.

  $ svn cp svn+ssh://smote.cs.berkeley.edu/code/foo/trunk svn+ssh://smote.cs.berkeley.edu/code/foo/tags/mybranch'
  

• Suppose some changes were made to trunk that we want to pick up. Merge trunk into mybranch. This updates your working directory with the merge-- after doing this, 'svn diff' will show the changes and you can then commit or reject them.

  $ cd <my branch's working directory>
  $ svn merge svn+ssh://smote.cs.berkeley.edu/code/foo/trunk .
  

• I just checked in some changes which I don't like. Revert them. Suppose the good revision was 1023. Do this in the working directory-- you actually do this with a "backwards merge".

  $ svn merge -r HEAD:1023 .