LINUX GAZETTE EDITOR'S GUIDE TO SUBVERSION
2003-02-09 Sluggo
Updated 8 Jul 2006 Ben

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/

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

- Email your SSH public key (DSA is preferred) to editor@linuxgazette.net;
  it will be added to the staff (i.e., 'gazette') account. If you don't
  have an SSH key, create one by running 'ssh-keygen -t dsa' on your
  system; the file you need to send will be located in ~/.ssh and will be
  called 'id_dsa.pub' or 'id_rsa.pub'.

- Install the "subversion" package in your Linux distribution (preferred),
  or compile it from source (http://subversion.tigris.org/).

- Set this environment variable in your ~/.bash_profile:

    export SVN_SSH='ssh -l gazette'

- IMPORTANT: For those getting an account of their own - i.e., other than
  'gazette' - be sure to set the umask on your new account to '002' (this
  is done in your ~/.bash_profile on the LG server.) If you don't, it'll
  generate ugly error messages for everybody else and require hunting down
  the offending files in $REPOSITORY/db.

- Make sure you have a relatively fast network connection - the download is
  going to be over 200MB - and run the following command:

  svn checkout svn+ssh://genetikayos.com/var/svn/linuxgazette.net
	
  This will create the local directory structure on your system; unless you
  specify an optional target directory, it will be located in the same
  place as the source directory on the repository machine (i.e.,
  '/var/svn/linuxgazette.net'.) Note that $LG (or $LG_ROOT) in all further
  documentation refers to '/var/svn/linuxgazette.net' from the above
  example, or wherever your working copy lives if you've placed it
  elsewhere.

- Copy $LG/doc/lgrc to ~/.lgrc and customize it for your system; then,
  source it whenever you run a shell by adding

  source ${HOME}/.lgrc

  to your ~/.bashrc (or, if you run a shell other than Bash, to whatever
  that shell's equivalent of the per-console rc file happens to be.)

- If you want to generate finished files for HTML preview, or to upload
  those files to linuxgazette.net, you need to create a destination
  directory (whatever you've specified as $LG_WWW in ~/.lgrc).

==============================================================================
BASIC LG SUBVERSION TUTORIAL

Repository: the central database of the LG files tracked by SVN.
Sandbox (working copy): 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 the source files alone require.

The Subversion book has a good tutorial of the commands, and also has an
appendix for CVS users; I suggest creating a local copy of that tutorial on
your machine and referring to it often until you've memorized the few
necessary commands. Use the "svn help" command as a good reminder of the
basic syntax.

You're welcome to create a $LG/p/my_username/ directory 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. You can also tell SVN to ignore these files by
using the 'svn propedit svn:ignore <dirname>' command, which allows you to
enter the filenames and subdirectories (wildcards are allowed) to be
ignored in a given directory; that way, the 'svn status' command will not
list these as unknown ('?'), and they will not be uploaded to the
repository.

We are not using "tags" and "branches".  If you need to make a private
branch, copy the required directory into your scratch directory and tell
SVN to ignore it, as above.

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.

==============================================================================
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 (if you're a member of group 'lgang'; otherwise,
ask a staffer) 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.


If you really, *really* hose a subdirectory - say, by deleting '.svn' or
something similarly awful - then delete it ('rm', not 'svn rm') from the
SVN tree and run 'svn revert <subdir_name>' from its parent directory.
Note that this will lose any of the work you've done, so copy any changed
files out of that directory and move them back in after 'svn status' shows
that everything is back to normal. If you get in *really* bad trouble,
email the editor (Ben), who has made all the stupid mistakes^W^W^W^W^Wa lot
of experience with SVN and knows where to get the right chainsaw.

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

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


# vim: sw=4 ts=4 expandtab ai