Terapix Star Formation Region IC 1396, © 2001 CFHT
Last content update March 13th, 2005

The TERAPIX Subversion server is installed on terapix.iap.fr.
There are two repositories, a public one and an internal one.

The public repository is /public or /var/local/svn/public and can be accessed by anyone without authentication for reading.
The global tree is
/public/software for publicly released softwares
/public/documents for public documents (articles, documentation).

The private repository is /private or /var/local/svn/private and can be accessed only by TERAPIX members.
The global tree is
/private/software for internal or unreleased softwares
/private/documents for internal documents

The main commands to know are:


Basic principles

-  A version control software is a system that manages files and directories over time. Every change made to any file or directory is stored in the repository so a complete history of data and versions is saved. The main interest is that older versions can be recovered and several versions can be done simultaneously by different persons without losing any information.

-  The Subversion server installed on terapix.iap.fr uses a specific protocol by joining ssh and svn servers. There are two local repositories: /var/local/svn/public/ and /var/local/svn/private/ but symbolic links /public and /private also exists. Consequently, the protocol must be specified using the URL
svn+ssh://terapix.iap.fr/var/local/svn/public or shorter svn+ssh://terapix.iap.fr/public. The two are exactly the same. Of course, public can be replaced by private to access the private repository. In the following, examples will be given mostly for the public repository only but the private one works the same.

-  When connecting to Subversion using this protocol, only the ssh login and password are needed. An environment variable can be set to configure the connection :
SVN_SSH="ssh -l <username>"

The default ssh port (22) is blocked by the IAP firewall, but another ssh port (2200) accessible from anywhere has been set up. So for access outside the IAP you may configure the SVN_SSH environment variable as
SVN_SSH="ssh -l <username> -p 2200"

Basic commands

-  Initial import
As you start to share a new project, you have to send your local tree to the server. The appropriate command is import. Typically, it looks like
svn import <local_directory> svn+ssh://terapix.iap.fr/private/<sub_directory> -m "<import_message>"

where <local_directory> is the root directory of your project, <sub_directory> the sub-directory where to copy your files and <import_message any comment you think valuable. Warning: it is very important to set <sub_directory> or your files will be directly copied to the root repository.

-  Initial checkout
When a project is available on the repository and you want to download it to a local computer where it does not exist, you just need to checkout the project:
$ svn checkout svn+ssh://terapix.iap.fr/public/<sub_directory>

This command creates <sub_directory> in your current directory and recursively copies every file and directory from the repository. You can specify a version to checkout by using the --revision option:
$ svn checkout --revision <nb> svn+ssh://terapix.iap.fr/public/ <sub_directory>

To have a repository history, the log command is useful:
$ svn log svn+ssh://terapix.iap.fr/var/local/svn/public/<sub_directory>

The --revision option can be used with the log command.

-  Update
When working with other users on the same project, you may want to get a local version of the latest revision available in the repository. As you already have your own version on your computer, you only want to get the modifications by updating it:
$ svn update

You do not need to specify any other information as your local working directory contains information about the Subversion repository. A list of modifications will be displayed.

Before starting modifying a project, always update your local version because someone may have submitted a new version in the meanwhile.

-  Changes
Once you have downloaded/updated your local version, you can edit files, create and remove directories, etc.
If you edit an existing file, you do not need to tell Subversion that you intend to change the file, Subversion will detect the modifications for you.
But, if you create new files and directories you need to inform Dubversion by using specific commands:
$ svn add <file>

By default, the add command is recursive. To avoid this, the -N option can be added to the command line.
$ svn add -N <file>

Other commands exist, like delete, copy and move but it is recommended to use them with great care. Be careful with any modification you do locally before exporting it to the repository. Any modification creates a new revision so it can become a real mess.

To check any modification you did, you can use diff command.
$ svn diff

For each file, you will see changes made to your current working version compared to the latest known revision on the repository.

-  Confirm changes
Once you have modified your version and you are satisfied with it, you may send it as a new revision to the repository:
$ svn commit

If you are the only one currently working on the files, the process will simply create a new revision and update any modified or created file according to the changes you specified. You can use the -m option to add a message.

But, the main interest in using a version control system is to allow several users to modify a common project. So problems may be encountered while commiting. If someone committed a revision newer than the one you have just updated, conflicts will be detected and your commit will be refused. You now have to ask for an update.
$ svn update

Subversion will insert lines in your working copy containing the repository latest version changes.

-  Resolving conflicts

Once you have finished editing your own files, you have to resolve conflicts in order to be authorized to commit a proper version.

To see the conflicting file(s), use the diff command
$ svn diff

Then, edit each conflicting file to solve the conflicts. It is very important to know exactly what you do in order not to commit a non working revision. Always test your revisions before committing.

Once your revision is ready, tell Subversion which files are not conflicting anymore:
$ svn resolved <files...>

where <files...> is a list of previously conflicting files that you just modified. You can now commit your changes.

Standard procedure

The first command to use is svn import or svn checkout to receive what is called the Basic work cycle :

-  Update your working copy (svn update)
-  Make changes (edit files, create files and svn add)
-  Examine changes made to the files (if needed svn update and svn diff)
-  Merge the changes with those made by others (edit conflicting files and svn resolved)
-  Commit changes (svn commit)


-  First, send a new project to the repository.

$ svn import basix-0.1.8 svn+ssh://terapix.iap.fr/private/software/basix -m "Initial import of version 0.1.8"
$ svn list svn+ssh://terapix.iap.fr/private/software/

$ svn list svn+ssh://terapix.iap.fr/public/software/basix

-  Then, change our local version by editing the files. Let us add the line
Anthony Baillard (baillard@iap.fr) in AUTHORS. We can have a look at our changes:

$ svn diff
--- AUTHORS     (revision 28)
+++ AUTHORS     (working copy)
@@ -0,0 +1 @@
+Anthony Baillard (baillard@iap.fr)

-  confirm our changes.

$ svn commit
Log message unchanged or not specified
a)bort, c)ontinue, e)dit
baillard@terapix.iap.fr's password:
Sending        AUTHORS
Transmitting file data .
Committed revision 29.

-  Make other changes locally. Let us edit for example the README file and add the line testing1. Try a commit:

$ svn commit

Log message unchanged or not specified
a)bort, c)ontinue, e)dit
baillard@terapix.iap.fr's password:
Sending        README
Transmitting file data .svn: Transaction is out of date
svn: Commit failed (details follow):
svn: Out of date: '/basix/README' in transaction '1a'

This means that someone else edited and commited README. So we have to update our version:

$ svn update
baillard@terapix.iap.fr's password:
Updated to revision 30.

Then, search for differences:

$ svn diff
--- README      (revision 30)
+++ README      (working copy)
@@ -1 +1,3 @@
\ No newline at end of file
+<<<<<<< .mine
+testing>>>>>>> .r30

Edit README and delete everything but testing. Finally, confirm our changes:

$ svn resolved README
Resolved conflicted state of README

$ svn commit -m "README resolved"
baillard@terapix.iap.fr's password:
Sending        README
Transmitting file data .
Committed revision 31.

$ svn log --revision 30:31
baillard@terapix.iap.fr's password:
rev 30:  baillard | 2005-02-24 17:19:55 +0100 (Thu, 24 Feb 2005) | 1 line

rev 31:  baillard | 2005-02-24 17:49:44 +0100 (Thu, 24 Feb 2005) | 1 line

README resolved

Full documentation

Subversion documentation - 1.3 Mb
Subversion documentation
(PDF, 1.3 Mb)

Site Map  -   -  Contact
© Terapix 2003-2011