Subversion Intro for Class Web Pages                              reid@umn.edu
------------------------------------

The web page is version-controlled with Subversion (SVN). This means that a
complete history of all changes to each file is stored in the "repository",
giving us a nice way to see who changed what and revert bad changes. SVN also
greatly simplifies multiple people working on the pages and helps resolve
incompatible changes, and it provides a way to preview changes before making
them live on the real web site.

The Prime Directive of working with a web page that's controlled this way:

  --> Do not edit in the web directory (/web/classes/...) <--

While it it possible to edit in-place in the web space and then check in your
changes, I strongly discourage this because it's very persnickety to get the
permissions right, and it's easy to forget to check in your changes. We had
trouble continually in previous semesters with permissions. Instead, I
recommend you check out your own copy and work on it on the UNIX machine of
your choice. Here's what you need to get started:

To "check out" a working directory, that is create an area for you to make
your own changes, use one of two commands:

  % svn checkout file:///web/classes/Spring-2006/csci1902/SVNROOT/csci1902www
  % svn checkout svn+ssh://oxygen.cs.umn.edu/web/classes/Spring-2006/csci1902/SVNROOT/csci1902www

Both work on CS cluster UNIX machines, but only the latter works off-site. The
latter requires you to enter a password on every operation unless you set up
SSH public keys and use ssh-agent. (Note also that if you work off-site and
use the department PHP web templates, previewing your work will be non-trivial
because you will have to match the department's template setup.)

This command creates a directory called "csci1902www" containing everything in
the web space -- this is your "working directory". You will edit here and
then, when you are done, arrange for your edits to show up in the web space.
You can rename this directory if you like.

Once you're checked out a copy of the web page, the work cycle goes like this:

  1. Grab any new changes from the repository ("update")
  2. Make your edits (add, change, remove files)
  3. Check your changes into the repository
  4. Update the web space, making your changes visible to the world

To grab the latest changes: (Do this before every editing session. SVN can
help with merging changes, but it's easier to avoid such situations.)
 
  % cd csci1902www
  % sh updatewww.sh

updatewww.sh is a shell script that updates your working directory with the
latest repository changes and then performs a little magic to ensure that
permissions are correct throughout your working directory. If you arrange for
your working directory to be accessible from the web, file permissions are all
that keep private data from being accessible to the world. In this case, IT IS
VERY IMPORTANT YOU USE THIS SCRIPT INSTEAD OF UPDATING WITH SVN DIRECTLY. See
the shell script itself for more information (which I suggest you do).

Any files or directories you create need to be added, with:

  % svn add FILENAME

(SVN does not require special treatment of binary files, as CVS does.)

Edit within your working directory as you wish. When you are done, commit your
changes with:

  % svn commit -m "comments about my changes"

You can specify files or directories to commit. The default is "." (i.e. the
current directory). It is a good idea to check if you've forgotten to add any files before you commit:

  % svn status

If SVN prints files with "?", that means SVN doesn't know about them: you may
have forgotten to add them, or there may be another reason for this. Question
marks aren't necessarily a bad thing. Another frequent gotcha is committing
only a subset of one's changes.

The last step is to update the web space with your fresh changes. Log into any
CS UNIX machine, change to the web directory, and say:

  % sh updatewww.sh

Again, IT IS VERY IMPORTANT YOU USE THIS SCRIPT!

Feel free to ask me questions about Subversion. The documentation is on the
Web at: <http://svnbook.red-bean.com/>.


Setting up SVN for ITLabs Course Web Pages
------------------------------------------

These are my notes that I use to get things started. Don't use these commands
unless you know what you're doing. They are not necessary for normal SVN use.

cd /web/classes/Spring-2006/csci1902/
umask 007
mkdir SVNROOT
svnadmin create --fs-type fsfs $PWD/SVNROOT/csci1902www
svn checkout file://$PWD/SVNROOT/csci1902www
mv csci1902www/.svn .
svn propset svn:ignore 'SVNROOT' .
rmdir csci1902www
svn commit -m "set up repository"

Ready. Working directory root is now /web/classes/Spring-2006/csci1902/.
(Don't add SVNROOT to SVN.)