How to share code/results/figures

The Browse Source tab at the top of this wiki will allow you to browse the code we have written for this project.

This is a Subversion code repository, which helps us stay organized as multiple people create and use multiple copies of the same code.

The IT department at LEGI has written a  good introduction, there is also a  free online book with a good section on the basics of how to use Subversion (SVN).

Ultra-minimalist introduction

The idea is this: there is a folder on the LEGI server (servforge.legi.grenoble-inp.fr) that is the principal repository of our code (or figures/results etc.). Everyone has a similar folder on their computers. You can create or modify a script as you normally would on your computer, and then use SVN to 'publish' your new code or modified code to the repository. If you have modified a piece of code that already exists in the repository, the old version is saved and accessible, and it is very easy to compare code and track changes.

Step-by step

* The first step is to install Subversion. If you use linux or mac you probably already have it on the command line, and if you use windows you can use  the client recommended by the IT department at LEGI.

* The next is to 'check out' a working copy of the repository on the server

I'm using linux, and would like my local folder to be called 'nicks_working_version' and be on my desktop, so from the '~/Bureau' folder I used the following command:

stelzenm3n@edt7pcnm83:~/Bureau$ svn co https://servforge.legi.grenoble-inp.fr/svn/pj-edt-16channel/trunk nicks_working_version/

This command creates the local folder 'nicks_working_version' on my desktop (notice my current directory is ~/Bureau$) and 'checks out', or copies, the svn respository from the svn server to my local folder.

* The basic work cycle is as follows:

** Update Before I change any of the files in my local directory, I want to make sure my copies of everything are up-to-date. In linux I can do this by going to my local folder (in my case ~/Bureau/nicks_working_version) and using the svn update command

   stelzenm3n@edt7pcnm83:~/Bureau/nicks_working_version$ svn update
   À la révision 8.

This command updates my copy of the repository and gives my the version number.

** Add and Modify In my local copy of the repository I can modify files that already exist in the repository, or add new folders and files as I wish. These changes are remain local (i.e. the repository on the server is not changed) until I publish my modifications. For example, I add a text file 'toto.txt', and modify an existing file 'README.txt' I need to tell the svn to add the file explicitly with the following command:

stelzenm3n@edt7pcnm83:~/Bureau/nicks_working_version$ svn add ESWIRP_data_processing/LEGI_hotwire/survey/raw_survey_data/toto.txt 
A         ESWIRP_data_processing/LEGI_hotwire/survey/raw_survey_data/toto.txt

The add command is recursive, so if I add a folder (e.g.ESWIRP_data_processing/LEGI_hotwire/survey/) all of the files and folders contained in that folder are added.

When I use the svn status command:

stelzenm3n@edt7pcnm83:~/Bureau/nicks_working_version$ svn status
M       ESWIRP_data_processing/LEGI_hotwire/data_retrieval/README
A       ESWIRP_data_processing/LEGI_hotwire/survey/raw_survey_data/toto.txt

I can see an 'M' for modified, and an 'A' for added next to these two files. This shows me how my local copy of the repository differs from the copy I 'checked out' earlier.

** Publish

In order to publish your changes you need to use the svn commit command. For me, that looks like:

stelzenm3n@edt7pcnm83:~/Bureau/nicks_working_version$ svn commit
Envoi          ESWIRP_data_processing/LEGI_hotwire/data_retrieval/README
Ajout          ESWIRP_data_processing/LEGI_hotwire/survey/raw_survey_data/toto.txt
Transmission des données ...
Révision 8 propagée.

You will be given a chance to write a short comment about your changes; That is it! Your changes are now on the server, and everyone can see them. If we go to the Browse Source tab of this wiki and look at the README file we can see that the file has been changed on 23/01/15 by stelzenm3n , and by clicked the view changes button we can compare the new and old versions to see exactly what changes were made.

Tortoise SVN

Tortoise SVN is the prefered SVN utility if you are using windows. It is a shell helper utility, which means after you install it you should see additional options when you right-click on a file or folder. All of the above ideas are relevant, and the work cycle is the same. You will see more options than I have described above, but these can be ignored for the moment.

* Checkout: Simply create a folder somewhere that will act as your local copy of the repository. Then, right-click on the folder, and use the 'SVN Checkout' option. It will ask you for an address to the repository, use:

https://servforge.legi.grenoble-inp.fr/svn/pj-edt-16channel/trunk

The other default setting are fine. Your login and password will be required as well.

* After checkout, a copy of the repository should be on your computer. Before you begin work, right-click on your local folder and run the command 'SVN Update'

* If you add a file or folder to your local copy of the repository, right-click on the file or folder you added and run the command 'Add'

* When you have finished adding and modifying files and folders, right-click on your local copy of the repository and run the command 'SVN Commit'. Add a comment, such as what you added/modified and why, and click OK.

Executive Summary

Details will probably differ depending on you operating system, but the basic commands and workflow should remain the same:

* Checkout: svn co allow you to make an initial copy of the repository and get started.

*Update: svn update makes sure you are working with the latest copy of the repository.

* Add: svn add allows you to add files and folders recursively.

*Check status: svn status shows you how your local folder is different than the repository. If you see a question mark you probably forgot the 'add' step.

*Publish: svn commit lets you push you new files and modifications to the shared repository on the server. Remember that older versions are still accessible.

Modify this wiki

I have tried to be clear and simple to help you get started, but I left a lot out. If you run into any problems (and hopefully solutions!), especially with the use of SVN on windows and mac, please add/modify this wiki. It is easy, just hit the 'Edit Page' button and use what is already here as a guide for formatting. I found TracLinks and WikiFormatting to be helpful.