LINUX GAZETTE EDITOR'S GUIDE TO SUBVERSION
2003-02-09 Sluggo
Updated 2010-12-28 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.
  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 (and optionally,
  your ~/.xprofile):

    export SVN_SSH='ssh -l okopnik'

- Make sure you have a relatively fast network connection, and run the
  following command:

    svn co svn+ssh://linuxgazette.net/home/okopnik/svn/linuxgazette /var/svn
	
  It will create the local directory 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
reasonable, 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.

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

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


# vim: sw=4 ts=4 expandtab ai
