Very Basic Subversion (SVN) Crib Sheet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

0. Introduction
-------------------

0.1 Scope

This is a crib sheet for working with the THEMIS software using
the SVN command line interface.   It is written in
UNIX style, but the same SVN commands can be used from the 
WINDOWS cmd window (only the path separators and environment
will be different).  

0.2 Requirements

SVN and SSH must be installed on your system.  

Details of installation are beyond the scope of this document, 
as they vary from system to 
system.  Please consult with your system administrator, if necessary.

The WINDOWS SVN command line interface is available for
download from http://subversion.tigris.org/files/documents/15/35379/svn-1.4.2-setup.exe
A suitable SSH client on Windows is PuTTY.   PuTTYgen and Pageant should
be installed along with PuTTY.

1. Getting Started
-----------------------

1.0 Basic SSH setup

Generate an SSH key pair (which consists of a public key and a private key):
> ssh-keygen -t rsa

You will be prompted to enter a passphrase for your private key. 
Enter a passphrase to make your key pair secure.  You may
want to consider using an ssh agent, described in the Other Commands
section, to avoid being prompted for a password when using SVN commands.

Alternatively, you may choose to use an empty passphrase for your key--you
won't be prompted for a password when you use SVN commands--but
guard your private key well:  anyone who obtains a copy of your private 
key file can access any machine where your public key is authorized.  

If you choose the default location for your key,
your public key will be saved in .ssh/id_rsa.pub 

Email your public key to jimm@ssl.berkeley.edu or
pcruce@igpp.ucla.edu.  We will use your public key to authorize access
to the SVN repository.

1.1 Setup

1.1.1 Environment 
To get set up (on most machines at SSL):

> source /disks/socware/toolchain/current/setup

If this does not work for you, try running 
svn --version
to see if your sysadmin already has svn installed.

The setup script does two things which you can easily do for yourself:

1) Set your path to point to the location where SVN is installed on your
system (this may already be done for you by default).  

2) Set the SOCREPOS environment
variable as a shortcut to the location of the SOC Subversion repository 
(where the THEMIS software repository lives) :

setenv SOCREPOS svn+ssh://thmsvn@ambrosia/repos

or for bash:
export SOCREPOS; SOCREPOS=svn+ssh://thmsvn@ambrosia/repos

I'll be using this environment variable as a shorthand for the repository
 URL in the following notes.

for READ ONLY access (at SSL -- no requirement for  SSH!), you can set
setenv SOCREPOS file:///disks/socware/thmsvn/repos

1.1.2 Subversion configuration file

Run 
svn --version

This will create a .subversion directory in your home directory.
[On Windows, this will be a Subversion folder, most likely in the
Application Data directory within your profile directory]

Edit the .subversion/config file:
At the end of the [miscellany] section, uncomment the line to enable
auto-props:
enable-auto-props = yes

In the [auto-props] section at the end of the file, add the following lines:

*.c = svn:eol-style=native;svn:keywords=Author Date Rev URL Id
*.f = svn:eol-style=native;svn:keywords=Author Date Rev URL Id
*.pro = svn:eol-style=native;svn:keywords=Author Date Rev URL Id
*.cpp = svn:eol-style=native;svn:keywords=Author Date Rev URL Id
*.h = svn:eol-style=native;svn:keywords=Author Date Rev URL Id
*.dsp = svn:eol-style=CRLF
*.dsw = svn:eol-style=CRLF
*.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Rev URL Id
*.txt = svn:eol-style=native;svn:keywords=Author Date Rev URL Id
*.png = svn:mime-type=image/png
*.jpg = svn:mime-type=image/jpeg
Makefile = svn:eol-style=native;svn:keywords=Author Date Rev URL Id
makefile = svn:eol-style=native;svn:keywords=Author Date Rev URL Id

These lines in your configuration will ensure  that keyword substitution
will work properly in files that you add to the SVN repository.  Keywords
are discussed more fully below.

1.2 Checkout Your Own Workspace

To check out a working copy of the THEMIS software:

> svn checkout $SOCREPOS/idl_socware/trunk idl_socware

To check out a working copy of just the THEMIS-specific IDL code:

> svn checkout $SOCREPOS/thmsoc/trunk/idl/themis/ themis

2. Working with SVN
----------------------------

2.1 Commands you can use within your working copy

SVN has commands to add, move, delete, and copy files, as well
as set properties on files within your working copy.  

Note that action scheduled by these commands
does not affect the repository until you commit them.

To schedule a new file or directory to be placed under version control:

> svn add file_name

Each file should have the following keywords included (the SVN keywords are
similar to CVS an SCCS keywords, but SCCS keywords have a completely
different format).  

$LastChangedBy$
$LastChangedDate$
$LastChangedRevision$
$URL$

The keywords will
get substituted with the proper values automatically by SVN when you commit
your file to SVN.  For example, the above might be substitued with:

$LastChangedBy: kenb-mac $
$LastChangedDate: 2006-12-20 16:14:32 -0500 (Wed, 20 Dec 2006) $
$LastChangedRevision: 139 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/doc/thm_cribsheet_svn_cmd.txt $

For IDL files, let's add a VERSION heading after the HISTORY heading
in the auto-documentation area, so that the version info shows up in the 
IDL documentation:

;+
; NAME:
; SYNTAX:
; PURPOSE:
; INPUT:
; OUTPUT:
; KEYWORDS:
; HISTORY:
; VERSION:
;   $LastChangedBy$
;   $LastChangedDate$
;   $LastChangedRevision$
;   $URL$
;-

In order for SVN to make the keyword substitutions, you must
set the svn:keywords property on each file.  

If you configure your 
.subversion/config file as recommended in 
section 1.1.2 before committing your file to SVN, this step will be unnecessary: 
they svn:keywords will be set automatically by SVN.

If you need to do it manually, here's how to do that on the command line:

> svn propset svn:keywords "Author Date Rev URL Id" <file name>

To check if the svn:keywords property is set correctly:

> svn propget svn:keywords <file name>

To make a duplicate of a file: new file has same history as
original file up to time of copy:

> svn copy file_name new_file_name

to move a file or directory which is under version control:

> svn move file_name new_file_name

to remove a file from  the repository:

> svn delete file_name

To see at a glance which files have changed, been added,
deleted, or are not under version control:

> svn status

To see detailed list of changes to all or specified files in your
 working copy

> svn diff [path_name ...]

2.2 Commit and Update

To commit local changes to files (including adds, moves and
deletes scheduled with the above commands) to the repository:

> svn commit [--file logfile] [-m "commit message"] [path_name]

For the commit log comment: use --file logfile  to take the log
entry from a file, or the -m to enter the log entry on the command
line. If --file or -m are omitted, svn will allow you to enter a log entry by starting
up vi by default, unless you have specified a different editor by
setting the SVN_EDITOR  environment variable.  e.g. 

> setenv SVN_EDITOR dtedit 

If SVN_EDITOR is not
set, it will also check the VISUAL and/or EDITOR environment
variables, which are used by other UNIX programs (e.g. cvs).

Your commit will be blocked if someone else has committed changes
to files that you have changed in your working copy.

To see a status report which indicates if anyone
has committed any changes to the files that you have in your
working copy:

> svn status -u

To update your working copy with changes committed by others
to the repository:

> svn update

To update /disks/socware/idl with the changes you committed:

ssh thmsw@ambrosia
cd idl
svn update

2.3 Conflicts

You will be prevented from committing a file if there is 
a conflict between your edits and edits someone else has
committed to the repository.
To resolve the conflict, edit the file to resolve conflict 
and remove conflict markers
(<<<<<<, =======, and >>>>>>)
You can use the filename.mine, filename.rOLDREV and
filename.rNEWREV to help understand the difference between the
conflicted file and your orginal edits, your pristine copy before
your edits, and the new revision which someone else put in the
repository, respectivey. When you (an the person with whom you had the conflict)
are satisfied that you have resolved the conflict, run:

> svn resolved filename

and then SVN will allow you to commit your file.

Some commands that might help in determining the source of a conflict:

To find out who committed changes, and see their commit comments:
> svn log filename

To see which lines were changed (i.e. annotate lines by user and version number):
> svn blame filename


3. Other Commands
---------------------------

Other commands that may occasionally be useful:

3.1 Import

If you have a directory full of things that you want to import into SVN,
you can check out a working copy, move your stuff into the working
copy to the appropriate place, 'svn add' them, then 'svn commit' 
your changes.

Sometimes, it may be easier to work directly on the repository:

> svn import path/to/new/stuff $SOCREPOS/project/trunk/newstuff -m 'your commit comment'

Then, check out a version-controlled copy to work on with SVN.

3.2 Switch

It may happen that we need to change the URL where you access
the repository.  If you have a working copy that you want to switch
to use the new location of the repository:

> svn switch $SOCREPOS/new/location


3.3 SSH agent

The SSH agent is useful for eliminating the need to enter your SSH passphrase multiple
times while working with SVN.

For Windows, use pageant.

For UNIX:

To make sure the ssh-agent goes away when your terminal is closed (so as not
to open up a security hole), start an ssh-agent enabled xterm 
as a sub-process of ssh-agent:
 
> ssh-agent xterm &
Inside the the xterm run
> ssh-add

Or just start a sub-shell, e.g. bash:

> ssh-agent bash

> ssh-add

The ssh-agent will then go away when you exit your ssh-enabled shell.

If you don't want to start a new shell, you can start ssh-agent in your
current terminal session, but you will have to be careful to kill it manually when
you are done.

> eval `ssh-agent`
> ssh-add

When you no longer need the ssh-agent running, be sure to kill it, or
it will remain active even if you kill your terminal.
> ssh-agent -k