dOvs 2011

Creating a repository

To create a repository, please go to svn.nfit.au.dk. Log in with your normal NFIT user-ID and password. A special subversion password will then be created and sent to the email account corresponding to your NFIT user-ID.

When a repository is created an email will be send to your email account with information about the repository.

The same page can be used to manage repositories (e.g., to add your fellow group members) or to change your subversion password.

About Subversion

Subversion is a version control system. Basically that means a system that helps you collaborate on a software project (such as a dOvs compiler), by keeping track of all the changes you gradually make.

Subversion is already installed at DAIMI hence you don't need to install anything to use it at campus. However you may need to install a Subversion client on your private machine. Instructions for doing so are available on the Subversion homepage.

Here's a summary of some of the terminology connected with version control under Subversion.

a central 'repository' contains your 'project'.
a local copy of the project is typically stored in your DAIMI home directory and/or on your private machine.

To make things interesting one sends changes between the repository and the local copies.

To set things up you need to do two things:

You 'import' an initial directory structure to the repository, which will upload an initial version of the project.
You 'checkout' your project from the repository to download a local copy to work on.

With these two in place you are all set to work on your local copy.

Once you are happy with your latest changes to the local copy, you 'commit' (or upload) the changes back to repository.
To download the latest version you 'update' your local copy.
'add' allows you to add additional files and directories to an existing project.

Starting a project in a repository

Whether you are starting a project from scratch or already have some files and directories to include in your project, it is a good idea to create a reasonable layout of your project. Below we will create a standard TTB layout as described in the Subversion book.

We assume that you want to create a project called 'myproject'. To do so, we create a temporary directory, tmp, where we place the subdirectory 'myproject'. Inside 'myproject' you create three subdirectories: 'trunk', 'tags', and 'branches'. 'trunk' will contain the latest version of your project, 'branches' contains different, named branches of your main project, and 'tags' is for Subversion's bookkeeping. Consult the Subversion book for more details.

In total that adds up to the following nine steps:

   1. mkdir tmp
   2. cd tmp/
   3. mkdir myproject
   4. cd myproject/
   5. mkdir trunk
   6. mkdir branches
   7. mkdir tags
   8. cd..
   9. svn import https://svn.nfit.au.dk/svn/dOvs2011-groupXX -m "Initial project layout."

The last step imports the structure into the given repository and Subversion responds with a message along these lines:

Adding myproject
Adding myproject/trunk
Adding myproject/branches
Adding myproject/tags

Committed revision 1.

Now you are ready to check out a version of your project to work on.

If you want to add all the files and directories from the Joos compiler skeleton proceed as above and afterwards either run

 svn import https://svn.nfit.au.dk/svn/dOvs2011-groupXX -m "Added Joos compiler skeleton."

from the directory containing the skeleton, or check out a working version of the project, copy the skeleton to the working directory and add it (as described below).

Checking out from Subversion

You can check out a project using the Subversion client, svn, that accepts different commands (run 'svn help' for a description of these). One of the commands, checkout, requires an additional URL of the project you wish to check out. The checked out copy of the project will be saved to the currect directory:

  svn checkout https://svn.nfit.au.dk/svn/dOvs2011-groupXX/trunk

Using Subversion daily

Subversion can be used like CVS and most commands you might know from there have a Subversion equivalent. For example:

```
svn update
```
downloads the latest changes made to the current directory from the repository.
```
svn commit -m "put a descriptive comment about the latest changes here."
```
uploads any changes from the local copy (in the current directory) to the repository. If further changes have been made to the project since you last updated, svn will ask you to update to the latest version before you commit.
```
svn add SOMENAME
```
adds a file or directory called SOMENAME to the current project. Remember to commit the file after having added it.
```
svn diff
```
lists the differences between the local copy and the repository's version of the current directory.

In addition svn has a number of useful commands for moving and deleting files:

svn move
svn delete
svn rename

See 'svn help' for more commands and shortcuts.

Conflicts

When two users work on the same file and eventually submit their changes, Subversion needs to merge these changes into the central version at the repository. When changes are made to the same section of a file by two or more people there is a chance that their changes are incompatible (or at least Subversion cannot see how to merge them). In this case Subversion reports a conflict. It does so by marking the file with a capital C:

      ...
 C    .../mydir/myfile
      ...

You solve a conflict by manually editing the file in your text editor. The changes from each version will be indented with special tags like '>'. Once you have figured out how to merge the changes and deleted all the special tags, you need to run

 svn resolve mydir/myfile

to indicate to svn that you have worked out the conflict. Then commit the merged version back to the repository.

SubEclipse

There is a Subversion plugin for Eclipse called Subclipse. Subclipse is easy to install and use. See instructions for doing so here.

(Based on an earlier Subversion guide by Janus Dam Nielsen.)