Subversion crib sheet

These are some quick notes on using subversion with the MODAPS repository, with an emphasis on modifying the *.dbdat files, and pointing out some similarities to clearcase. Users should read the svn-book, particularly the Basic Usage chapter.

Subversion Concept Tips

Most svn commands act recursively on directory trees, unless you specify non-directory file(s), or the --non-recursive (-N) switch.
svn switches act the same in any subcommand they apply to, and they are all documented in one single place.
After creating a working copy from a repository, "svn" remembers the repository the files came from (saving you from spelling it out in most svn commands). A svn working copy is somewhat like a clearcase view that doesnt update automatically when other people modify the repository.

Startup instructions:

On a machine with svn installed, such as modular, create a MODAPS repository working copy and checkout any directory trees you want to work on. (We have "svn --version" -> 1.4.2.) Your working copy can be anywhere, the only real consideration is if you want to share it with anyone working with you. The repository host is not specified here for security reasons (even though it may not be accessible outside our network anyway).

  set repos = svn+ssh://$repos_host/MODAPS
  # or on the host itself: set repos = file:///MODAPS

  set wc = ~/svn_view/MODAPS

  mkdir -p $wc
  svn co -N $repos $wc
  svn co $repos/DB_Config $wc/DB_Config

You may want to change your subversion configuration on the host you use subversion. Set editor-cmd if you prefer an editor other than vi. Set global-ignores to list of filename patterns you never want to commit (may want to include *.a *.exe). (Note svn:ignore can be attached to a directory to add to ignore list for that directory (not recursively).)

  emacs -nw ~/.subversion/config

Before modifying or commiting files, update from repository:

If it has been awhile since your working copy was synced with the repository (checkout, update, or commit), you should check for and merge other peoples modifications into your working copy before you make changes or commit your changes back to the repository. Note again that without a path argument the svn commands work recursively on the current directory and its files.

  cd $wc/DB_Config
  svn status [-q]             # List local changes [ignore non-versioned files]
  svn status --show-updates   # List local and repository changes, PREVIEW update
  svn update                  # update local copy from repository

If you see a 'C' from update you need to follow the subversion documentation on resolving conflicts, or consult another user with experience in that. Have fun. This should be rare.

If svn update shows a 'G' in front of a filename, it means that svn has automatically merged changes into your modified file at different lines than the ones you modified. This is fairly likely and probably safe with *.dbdat files. However if you are paranoid, you might want to look into 'G' results:

  svn log $filename | more    # get most recent and most recent before
                              # your checkout revision numbers
  svn diff --diff-cmd diff -x '-w' -r $rev $filename
   or
  svn cat -r $rev $filename > $filename.$rev
  xdiff -w $filename.$rev $filename
  rm $filename.$rev

Because *.dbdat files in particular are modified by many people frequently, I recommend commiting changed dbdat files immediately after using them to update a database.

Commit changes to repository:

Once you are happy with your changes, and you've updated with recent repository changes, you can commit your changes to the repository. Please do commit all logically related changes in a single commit. Consider putting any applicable bugzilla number in the commit comment. Yet again, remember commit acts recursively on all changes in and below any specified directories (defaults to current directory), unless you specify non-directory filenames.

  svn commit -m "put commit comment here or get forced into vi or vim" [$filenames]

Make new directory or file elements

In your working copy use "svn add" to tell svn that you want directories or files added to the repository when you get around to commiting them:

  svn add $filenames

Versioning: simple and complex tagging

For svn tagging commands and comment suggestions for MODAPS see here and here.

PGE deliveries are likewise usually the latest code. A simple tagging process might apply to PGE deliveries although PGE**/, shared_lib/, etc. must all be tagged (all the CI directories the PGE uses).

Sparse Directory Tree Copy (or Checkout) in Subversion

The behavior of non-recursive vs recursive directory operations is Subversion is a bit tricky. Suppose you want to check out from a repository STORE/PGE99/... and STORE/shared_src/land_src/MOD_Mine/... where the "..." indicates recursive and you don't want the full contents of the other directories. The best way to do this is probably:

  svn co -N $repos       $wc
  svn co -N $repos/STORE $wc/STORE
  svn co -N $repos/STORE/shared_src          $wc/STORE/shared_src
  svn co -N $repos/STORE/shared_src/land_src $wc/STORE/shared_src/land_src
  svn co $repos/STORE/PGE99 $wc/STORE/PGE99
  svn co $repos/STORE/shared_src/land_src/MOD_Mine $wc/STORE/shared_src/land_src/MOD_Mine

NOTE: If you skip the "svn co -N" and create normal directories, there are some svn operations that wont work as well. (Which, I can't quite recall).

NOTE: directories not recursively checkedout will not handle recursive operations. This is important to remember when using "svn ci" (do review the list of modified files). For example even if changes exist in STORE/PGE400/..., this command won't descend past $wc to see them (note it doesnt know what STORE is):

cd $wc; svn status
?      STORE

Likewise suppose you want to make a sparse copy, for example to a branch or tag. The only way (I know) to do this is to create the non-recursive directories in the target location and then use "svn cp" on the parts that are recursive. For example:

  svn co -N $repos/branches       $wc/branches
  svn mkdir $wc/branches/prototype_PGE400 $wc/branches/prototype_PGE400/STORE $wc/branches/prototype_PGE400/STORE/shared_src $wc/branches/prototype_PGE400/STORE/shared_src/land_src
  svn cp $repos/STORE/PGE99 $wc/branches/prototype_PGE400/STORE/PGE99
  svn cp $repos/STORE/shared_src/land_src/MOD_Mine $wc/branches/prototype_PGE400/STORE/shared_src/land_src/MOD_Mine
  svn ci $wc/branches

Clearcase Commands and nearest svn equivalents:

Clearcase cmd	Subversion cmd
ct lsco -cview ct lsco -cview -rec ct ls -vie -rec	svn status -q -N svn status -q svn status
ct find . -ver 'lbtype(MODAPS_V4.0.00p008)' -print	svn diff --summarize -c 25210 $repos
ct lshist -user myName -since 1-Nov `ct find . -nxname -version 'created_since(1-Nov) && created_by(myName)' -print`	svn log -r 24000:HEAD \| grep myName svn log -r 25183:HEAD

svn and xdiff:

It is very useful to xdiff different revisions and the working copy. There is no built in way to do this, so there are several alternatives.

1) Create aliases (could be modified to allow revision specification):

alias svndiff 'svn cat -r BASE \!:1 > /tmp/svn.$$; diff /tmp/svn.$$ \!:1; rm /tmp/svn.$$'
alias svnxdiff 'svn cat -r BASE \!:1 > /tmp/svn.$$; xxdiff /tmp/svn.$$ \!:1; rm /tmp/svn.$$'
alias svngdiff 'svn cat -r BASE \!:1 > /tmp/svn.$$; gdiff /tmp/svn.$$ \!:1; rm /tmp/svn.$$'

2) Use the subversion python script which works with xxdiff (linux only). See http://xxdiff.sourceforge.net/local/doc/xxdiff-subversion.html, should be installed on our development linux boxes. To run subversion with xxdiff, the script "xxdiff-subversion" needs to be installed in /usr/local/bin by the system administrator (you could actually download it and put it in you own directory; if you did that you would need to edit your config file accordingly. (To use xxdiff with subversion, you must also change your ~/.subversion/config file to point to the location of the "xxdiff-subversion" script. The lines that you need in the script are "diff-cmd = /usr/local/bin/xxdiff-subversion" and "diff3-cmd = /usr/local/bin/xxdiff-subversion". ) Now "svn diff" will invoke xxdiff.

3) Or write your own wrapper, or copy mine (like above but works with xdiff or xxdiff). The key point is to examine the arguments fed to the diff-cmd, which are incompatible with xdiff, and trim before calling xdiff:

 cp ~devine/bin/svnxdiff.pl ~/bin/
 more ~/bin/svnxdiff.pl
In .personal:
 alias svnxdiff "svn diff --diff-cmd $HOME/bin/xsdiff.pl \!*"
 alias svnxdiffw "svn diff --diff-cmd $HOME/bin/xsdiff.pl --extensions '-b -w' \!*"

Use like "svn diff" (last two are equivalent):
 cd $repos
 svnxdiff Src/doc/Design/index.html
 svnxdiff -r 999 --extensions '-b -w' Src/doc/Design/index.html
 svnxdiffw -r 999 Src/doc/Design/index.html

References:

svn-book - THE subversion documentation, in detail.

Subversion best practices - Read "Commit logical changesets" and "Use the issue-tracker wisely" in particular. Short; mostly process ideas; possibly dated with respect to "svn mv".

viewvc - web browse through MODAPS directories and logs.

svn faq

[ Home ]