= Using repositories on the imaging server =

A code repository system allows you to have a secure copy of your code stored on the server that automatically keeps track of all your changes,
and allows you to track changes, and revert to older versions if you start finding you have broken your code.  It also allows you to keep the main
copy of your code on an internet server, so you can get at it from anywhere you can get the internet.

The server I have set up is the current standard, subversion:

http://subversion.tigris.org/

An example small repository is here:

http://imaging.mrc-cbu.cam.ac.uk/svn/html2moin

I strongly recommend that anyone developing code for themselves or others at the CBU, that is more than a few lines, consider using the repository system to
store it.  

In ordinary usage SVN is extremely straightforward once you have mastered a few commands.  In practice these are:
[[http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.checkout.html|checkout]], [[http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.commit.html|commit]], [[http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.add.html|add]], [[http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.update.html|update]], with occasional use of [[http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.status.html|status]] and [[http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.diff.html|diff]]. 

See http://svnbook.red-bean.com/nightly/en/svn.tour.html

== A note about the structure of SVN repositories on our server ==

After some discussion, we decided to go for a single project per repository model.

That means that we don't have subprojects in the repositories.

Instead of the normal subversion set of subdirectories:

{{{
repos/project/trunk
repos/project/tags
repos/project/branches
}}}

(where `trunk` - for example - contains the actual code), we've gone for a different naming scheme:

{{{
repos/devel
repos/versions
repos/branches
}}}

where `devel` - for example - contains the actual code.  You'll see an example lower down the page - the `cbudti` repository.  This is also set out in the section on making a new repository.

== Where is my code? ==

It's somewhere under http://imaging.mrc-cbu.cam.ac.uk/svn

You (and I) can't read that, but more usefully, an example, where the repository is `cbudti`:

http://imaging.mrc-cbu.cam.ac.uk/svn/cbudti/

And, more usefully still, the current development version of this code is in:

http://imaging.mrc-cbu.cam.ac.uk/svn/cbudti/devel

and, perhaps more usefully still, to get this code as a working directory, called `cbudti`

{{{
svn co http://imaging.mrc-cbu.cam.ac.uk/svn/cbudti/devel cbudti
}}}

== What do I do now? ==

Life is just plain sailing.

By running the `co` (checkout) command above, you have a new directory, called, in this case, `cbudti`.  In it is the code.

You work a bit on the code.  When you've worked for an hour or so, you think, 'I need to upload this stuff'.  So, you go:

{{{
cd cbudti
svn status
}}}

and get something like: 

{{{
?      new_file.m
M      tests/README
}}}

Not much for an hour's work, but still.

So, you've modified `tests/README` and added a new file `new_file.m`, which subversion doesn't know about yet.  So, obviously you do this:

{{{
svn add new_file.m
svm commit -m 'Some comment to remind you what these edits are for'
}}}

subversion may or may not ask you for your password, then you will see it sending files to the server.

One day, your code is so good that other people want to work on it too.  You give them permission to write to the repository (contact IanNimmoSmith or RhodriCusack for this), and they start work.  They upload changes as you have just done.  They tell you.  You want the changes.  So:

{{{
cd cbudti
svn update
}}}

and back come the changes from the repository.

You're working with someone who wants the new files.  Tell them to do what you've just done:

{{{
svn co http://imaging.mrc-cbu.cam.ac.uk/svn/cbudti/devel cbudti
}}}

- now they've got a copy of most recent code in the repository too.  If you do some more work, they can get it in the same way as you do:

{{{
cd cbudti
svn update
}}}

Or you want to point them to a particular file, perhaps the very latest version of the `tests/README`.  Send the URL:

http://imaging.mrc-cbu.cam.ac.uk/svn/cbudti/devel/tests/data/README

Or you've done some changes but you forgot what, and you're not sure if you want to keep them or not.  Say to the README file.

{{{
svn diff tests/README
}}}

gives you a list of the changes in your working copy compared to the one on the server.

All easy, all good.  When it isn't, come find / email RhodriCusack or IanNimmoSmith.

=== Using the DIFFUSE utility to handle reconciling diverged versions ===

While the output of '''diff''' between two files '''file1''' and '''file2''' is simple in principle, it is not so easy to work with to reconcile the two versions if there a significant number of changes. EleftheriosGaryfallidis and IanNimmoSmith have found that the [[http://diffuse.sourceforge.net/|'diffuse' tool]] provides a helpful graphical interface for viewing the texts in parallel with the common text passages aligned and the variant passages suitable highlighted. Both '''unix''' and '''Windows''' versions of '''diffuse''' are available. It is '''python''' based so you will need to have that installed too.

== How to I put my code into a repository as a new project? ==

You probably want to come and find IanNimmoSmith - but - if you want to do this yourself, here are the instructions.

First you'll need write access to a repository on our server.  If you want to make a new repository, see: [CbuLug:MakingRepositories] (only visible within the CBU) - but this will need to be done by someone with root access on the server - ask IanNimmoSmith or RhodriCusack.

Then create the default directory structure for repository and import code.

First make a directory tree containing the default project structure (see the note about the CBU tradition of repository structure above).  

{{{
mkdir repository_import
cd repository_import
mkdir devel
mkdir versions
mkdir branches
cd ..
}}}

Now, copy your code - say `file1.py` and `file2.py` into the `devel` subdirectory.

Let us say you that `repository_import` (above) is in `usefuldir`.

Then import your code, so that you will have (e.g.) `$REPOS/devel/file1.py` etc:

{{{
cd /path/to/usefuldir
export REPOS=my_repos
svn import repository_import http://imaging.mrc-cbu.cam.ac.uk/svn/$REPOS -m "Initial code import"
}}}

You can thence check out your devel code into a working directory with:

{{{
svn co http://imaging.mrc-cbu.cam.ac.uk/svn/$REPOS/devel my_working_copy
}}}

MatthewBrett and IanNimmoSmith