Editing Archive (section)

=Subversion (SVN)=
Subversion (SVN) is for accessing the source code of lab software. The code for Bone Lab software projects is stored in a subversion repository.

==Getting an SVN username==

To access the repository, you will need an account on mike.kin .  Ask Steve or Eric for one.

==SVN from the command line==

===Quick Usage: Downloading a Project for Compiling===

If you just want to get and compile one of the projects, but not modify the source code, this is the command that you want:

 svn export https://mike.kin.ucalgary.ca/svn/bonelab/trunk/faim

Replace "faim" with the project that you actually want to get and compile.

This assumes that SVN is installed already on your system.  See the section on installation if it is not.

===Checking out code for making changes===

If you want to work on the source code, then instead of 'export', you have to use 'checkout':

 svn checkout https://mike.kin.ucalgary.ca/svn/bonelab/trunk/faim

===Committing your changes===

Once you've made changes, and you're reasonably sure that the code still compiles and works, you can commit them with:

 svn commit

Do this from the directory that you checked out your code into.

Before you do this however, you should generally update your working directory to incorporate changes that other people have potentially made:

 svn update

Don't worry - you can lose any of your changes this way.  Most of the time, svn will successfully merge your changes with other changes, even if someone else has changed a file that you have worked on.  However, occasionally there will be a conflict with changes that someone else has made.  In this case, svn will require you to resolve the conflicts before you can successfully commit.  Refer to the relevant section of the SVN Book: http://svnbook.red-bean.com/en/1.5/svn.tour.cycle.html#svn.tour.cycle.resolve .

===Miscellaneous Useful Commands===

To find any files that have been changes since yoru last commit/checkout:

 svn status

To show the changes you've made to a particular file since your last commit:

 svn diff some_path/some_file

To get useful information on the current working directory (such as the URL originally used to check out the code):

 svn info

To get a history of the modifications to a particular file or directory:

 svn log some_path

To discard your changes to a file:

 svn revert

To add a new file or directory (note that if you add a directory, svn will automatically add all the files in that directory as well):

 svn add some_path

To get help on some particular svn command (in this example 'log'):

 svn help log

==Branches and Tags==

Usually you develop in the "trunk" of a project.  However, suppose you want to make some large changes that you might be working on for weeks, and not disrupt other people.  In this case, you can use a "branch", which is a copy of the trunk.  All your changes get committed to the branch, and do not affect the trunk.  Once you are happy with that state of your branch, you can merge it back into the trunk.

A "tag" is certain revision of the software that you want to "freeze".  Of course, svn will let you recover any particular revision, but a tag is a special revision, perhaps a known stable one that is given a version number.

In SVN, branches and tags are simply copies of the trunk that by convention go into the directories "branches" and "tags".  Don't worry that you might be consuming a lot of disk space by making copies of the trunk - svn makes "lazy" copies - only the actual changes are saved.  (If you've used CVS, you'll notice that branches and tags are different - and simpler - in SVN; they are just normal copies.)

Here is how you might make a branch of vtkMy named 'merge_vtkMy-lite':

 svn copy https://mike.kin.ucalgary.ca/svn/bonelab/trunk/vtkMy https://mike.kin.ucalgary.ca/svn/bonelab/branches/merge_vtkMy-lite

Similarly for a tag:

 svn copy https://mike.kin.ucalgary.ca/svn/bonelab/trunk https://mike.kin.ucalgary.ca/svn/bonelab/tags/version_2.2.0

Notice that for a tag, you should always copy ALL of the trunk.  For branches, how much you copy is up to you.  There is no harm in copying the whole trunk, even if you only want modify one little part in your branch.  This doesn't consume and additional disk space because svn makes "cheap" copies, for which only changes are saved.

Merging a branch back into the trunk can be slightly tricky.  I recommend that you read the relevant section of the SVN Book: http://svnbook.red-bean.com/en/1.5/svn.branchmerge.html .  If you have any doubt, come see Eric.

Here is the command actually used to merge the above example (merge_vtkMy-lite) back into the trunk.  In this case, once I was finished modifying the 'merge_vtkMy-lite' branch and had committed all the changes, I checked out a copy of the trunk, then from the working copy of the trunk, this was the command:

 svn merge --reintegrate https://mike.kin.ucalgary.ca/svn/bonelab/branches/merge_vtkMy-lite

After you've merged a branch back into the trunk, you should delete it:

 svn rm https://mike.kin.ucalgary.ca/svn/bonelab/branches/my_great_new_feature

This way, only currently active branches show up in the current revision, and it doesn't get cluttered with hundreds of old branches that are not interesting anymore.  Note that the branch is not really gone, since nothing ever is truly deleted from svn.  Anyone can checkout or otherwise access the particular range of revisions corresponding to between the times the branch was created and when it was deleted.

==Using a Web Browser to Browse the Repository==

You can browse the repository at https://mike.kin.ucalgary.ca/trac/ 

The web interface allows you to view directories and files, track changes, and view difference between particular revisions.  These are all things that can also be done from the command line, but the web interface is easier.

==Remote Access to Subversion==

NOTE: This is obsolete and possibly not needed.

The university firewall blocks access to the port used by svn from internet addresses outside of the university network.  This is a good thing.  If you're on a laptop or something, and want to be able to use the bone lab repository, it is still possible.  However, you'll have to check out things a little differently.  First, you'll need to have an actual account on splatter.  See Eric or Steve.  Secondly, you'll need to replace 'svn://splatter.kin.ucalgary.ca/' in all the above commands with 'svn+ssh://splatter.kin.ucalgary.ca/var/svn/bonelab' .  Note the additional path specification.  So for example:

 svn checkout svn+ssh://splatter.kin.ucalgary.ca/var/svn/bonelab/trunk/faim

You'll be asked for your password, which in this case will be your account password on splatter, and not your svn password.  To avoid having to type your password every time, set up RSA authentication, as described in [[ssh]].

It is also possible to access websvn from outside the university network.  Refer to the section on ssh tunneling at [[ssh]].

==Installing Subversion==

===OS-X===

Nothing to install, as svn is a standard part of OS-X.

===Ubuntu Linux===

 sudo apt-get install subversion

===Windows===

Get the installer from http://subversion.tigris.org/ .

==Graphical SVN Clients==

There are a number of graphical SVN clients for various systems.  For example, TortoiseSVN is a popular client for Windows, which integrates into the Windows File Manager.

See the list of clients at http://subversion.tigris.org/ .

==For Further Info: The Subversion Book==

A complete on-line book on subversion is available at http://svnbook.red-bean.com/.