LINUX GAZETTE EDITOR'S GUIDE TO SUBVERSION
2003-02-09 Sluggo

Subversion is a version control system similar to CVS but with several advanced
features.  The definitive background, tutorial and reference is the Subversion
book, available online at:
    http://svnbook.red-bean.com/
Subversion's home page is: 
    http://subversion.tigris.org/
Various quick references are also available:
    [URLs coming soon]

==============================================================================
CLIENT INSTALLATION

- Get a login account at linuxgazette.net (genetikayos.com)

- Install the "subversion" package in your Linux distribution, or compile from
  source (http://subversion.tigris.org/).  If you want to get fancy, you can
  use your Subversion binary to fetch the latest checked-in source!  See
  http://subversion.tigris.org/getting_subversion.html for that.

- Set this envvar:
    export SVN_SSH='ssh -l my_username'
  Where my_username is your account at linuxgazette.net.

- IMPORTANT: Set your umask to '002'. This is done in your .bash_profile.
  If you don't, it'll generate ugly error messages for everybody else and
  require hunting down the offending files in $REPOSITORY/db.

- cd to the directory your sandbox should go into, and run:
    svn checkout svn+ssh://genetikayos.com/var/svn/linuxgazette.net local_dir
  It will create 'local_dir' and put ~70MB of files inside it. You can use
  any directory name you want.  I prefer "lg"; the default is 
  "linuxgazette.net".  Whenever I say $LG or $LG_ROOT below, I mean this
  directory.

- Copy $LG/doc/lgrc to ~/.lgrc and customize it for your system.  Then either
  source it in your ~/.bashrc, or remember to source it before running any LG
  scripts.

- If you want to generate finished files for HTML preview or to upload to
  linuxgazette.net, create a destination directory ($LG_WWW in ~/.lgrc).
  In it, make a symlink 'gx' pointing to the 'gx' directory in your sandbox.
  That will allow the global images to display.

==============================================================================
SUBVERSION BACKGROUND

Repository: the central copy of LG editorial files.
Sandbox: your local copy of these files.

Every directory managed by Subversion has a .svn/ subdirectory; this is 
equivalent to CVS's CVS/ directory.  Unlike CVS, Subversion keeps a second
copy of every file in this directory.  This allows it to do some operations
without accessing the server, but it also means your sandbox will take up twice
as much disk space as expected.

Versions of Subversion after November 2003 supposedly don't need the SVN_SSH
envvar, you can use a URL of svn+ssh://my_username@genetikayos.com/... instead.
Use whichever works.

We are using the svn+ssh: access method instead of http: because of annoying
WebDAV errors we were receving with the latter.

The Subversion book has a good tutorial of the commands, and also has an
appendix for CVS users, so we won't dwell on them here.  Remember the 
"svn help" command.

You may make yourself a directory $LG/p/my_username/ and use it to experiment
with Subversion.  (p = personal)  That's also where you'll keep your scratch
files if any.  Just keep the total size of your scratch files small, and
remember to delete them from the repository when no longer needed.  Everyone
has permission to read/write your scratch files, so don't put any love letters
there.

We are not using "tags" and "branches".  If you need to make a private branch,
copy the required directory into your scratch directory (see "svn copy").

CVS users: Subversion can move directories just like files, while preserving
their history.  It has lazy copy (copy-on-write), so "svn cp big_tree dest"
does not waste time or bandwidth.  Every file/directory can have "properties",
which are arbitrary key/value pairs.  We are not using properties yet, but they
are used to do the equivalent of .cvsignore among other things.

==============================================================================
SUBVERSION TROUBLESHOOTING

If you get an error like this or an access error:

% svn update
svn: Couldn't find a repository
svn: No repository found in 'svn+ssh://genetikayos.com/var/svn/linuxgazette.net'
svn: Berkeley DB error
svn: Berkeley DB error while opening environment for filesystem /var/svn/linuxgazette.net/db:
DB_RUNRECOVERY: Fatal error, run database recovery

Ssh YOU@linuxgazette.net (as a member of group 'lgang') and do:
- svnadmin recover /var/svn/linuxgazette.net
- chmod g+w -R /var/svn/linuxgazette.net
See chapter 5 ("Repository Recovery") in the Subversion book for more info.

==============================================================================
FRONT ENDS

'rapidsvn' is a graphical front end to Subversion.
http://rapidsvn.tigris.org/

=============================================================================
IGNORING FILES

Don't add generated files to Subversion.  Not only are they redundant, but
they may generate differently depending on the user's Python version.
Put the human-maintained source in SVN instead and a Makefile that does
the generation conveniently.  This applies mainly to .py template modules
in $LG/lib/python/, which are generated from .tmpl files.

To prevent 'svn status' from displaying a "?" for generated files, do this:
- svn propset svn:ignore FILENAME

# vim: sw=4 ts=4 expandtab ai