LINUX GAZETTE EDITOR'S GUIDE TO SUBVERSION
2003-02-09 Sluggo
Updated 2006-02-27 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/
Various quick references are also available:
    [URLs coming soon]

==============================================================================
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'.

- Install the "subversion" package in your Linux distribution, or compile 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, and run the
  following command:

    svn checkout svn+ssh://genetikayos.com/var/svn/linuxgazette.net
	
  It will create the local dirctory structure (~168MB at this time, i.e.
  just before issue #124.) Note that $LG (or $LG_ROOT) in all further
  documentation refers to '/var/svn/linuxgazette.net' from the above
  example, or wherever your sandbox 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 .

- 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.

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

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.

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'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.

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 (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.

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

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


# vim: sw=4 ts=4 expandtab ai