Slicer:git-svn

Intro

As of 2010 the 3D Slicer projects use subversion (svn) for the main repositories. Many project are switching to git and many developers prefer it, but feedback is also mixed about just how easy it is for a large distributed team to standardize on a set of workflows and stick with them (much anecdotal evidence and hearsay omitted).

But, individual developers or groups can use git for their work and then commit the results back to svn. The info here provides a brief set of hints for this.

Prerequisites

Install git and git-svn on your machine (git svn is an add-on package, requiring an extra apt-get install on ubuntu).

For these instructions we'll assume you are using github so make yourself an account there (it's free and pretty simple). Configure the account with your email, name, and ssh keys. The git tutorials are never-ending, so don't try to read them all at once. The only way to get good with git is to play around with some dummy repositories while reading various documents until you feel reasonably confident with the way things work.

Make a local clone of Slicer

git svn clone -s -r 15000 http://svn.slicer.org/Slicer3

The -s says that slicer uses the standard trunk/tags/branches svn layout and the -r says grab the code at revision 15000 (just to keep things smaller).

Then update to get the most recent:

cd Slicer3
git svn fetch
git checkout master

push it to github

On github, create a new repository for your account called Slicer3.

Then set up a 'git remote' (basically an alias) to your git hub repository:

git remote add pieperSlicer3 git@github.com:pieper/Slicer3.git

(of course, replace occurrences of 'pieper' with your github username!).

The following command will populate the github master with your Slicer3 master (which is based on trunk).

git push pieperSlicer3 master

Create a topic branch

The 'branchy workflow' method of git is cool because all the changes related to a topic (meaning bug fix, feature addition, refactoring...) can be encapsulated in a lightweight branch that you can easily share with others.

Create a branch called "testbranch" for implementing our topic:

git checkout -b testbranch

(use 'git branch' to list branches and see that you are currently on the testbranch).

Now do some edits. If you create a new file, add it for tracking like so:

echo "new stuff" > newfile
git add newfile

As you make the changes, commit them to your local copy and give descriptive comments:

git commit -am "ENH: added a new file with new stuff  ..."

(in reality we prefer that you don't use the -m flag and instead us your editor to write a fairly long commit message with as much detail as you can stand to type). Also be sure to start your commit message with ENH, BUG, COMP, STYLE... for compatibility with the slicer svn rules.

Whenever you want to sync this up to github, just do:

git push pieperSlicer3 testbranch

Now if you look at the github repository it will have your new branch and commits. And you can easily email the link to the diffs off to your collaborators. They can review them, or check them out, make their own clones, or (with your permission) edit and commit back to your branch.

Merging back to the master

Once you have the code from the branch just the way you want it, you can merge it back to the master:

git checkout master
git merge testbranch

Since we're done with this branch, we can clean it up:

git branch -d testbranch

And, we can get rid of it off of github:

git push pieperSlicer3 testbranch --delete

or

git push pieperSlicer3 :testbranch

Committing back to svn

Bring your local master in sync with svn by doing, essentially, the same as 'svn update':

git svn rebase

then you can commit

git svn dcommit

How it looks in svn

These are normal svn operations, so once they are commited (with dcommit) they show up as normal:

File created: http://viewvc.slicer.org/viewcvs.cgi?rev=15512&view=rev File modified: http://viewvc.slicer.org/viewcvs.cgi?rev=15514&view=rev File deleted (using svn, just for cleanliness): http://viewvc.slicer.org/viewcvs.cgi?rev=15513&view=rev

More git resources

(There is more info on git than anyone can really digest - unfortunately I often find that the information you need is not exactly described by the man page or tutorial you are currently reading. The only solution is to read widely, don't believe everything you read, skip the parts that seem too wordy or abstract, and experiment a lot.)

Here are a bunch of links that may help:

• https://cirl.berkeley.edu/mb312/gitwash/index.html
• http://www.itk.org/Wiki/ITKContribute
• http://www.dinnermint.org/tutorial/dead-simple-git-workflow-for-agile-teams/
• http://www.vtk.org/Wiki/VTK/Git
• http://public.kitware.com/Wiki/Git/Workflow/Topic
• http://techblog.floorplanner.com/2008/12/14/working-with-git-branches/
• http://gitref.org/
• http://tom.preston-werner.com/2009/05/19/the-git-parable.html
• http://www-cs-students.stanford.edu/~blynn/gitmagic/ch02.html
• http://github.com/pkgwdemo/bloomdemo
• http://marklodato.github.com/visual-git-guide/#merge