Introduction

Subversion allows users to keep track of changes made over time to any type of electronic data. Typical uses are versioning source code, web pages or design documents (wikipedia).

Getting started with Subversion

This tutorial is intended to get you up and running with the subversion repository we use to host the code for this project. It covers installing svn on your own computer, and then using this to connect to the googlecode repository where our code resides.

This tutorial mainly lists the concrete commands you'll use to get connected - it doesn't cover the general concepts of version-control in much depth. If you are new to version-control, you will want to read something more comprehensive as well. A good place to start is the official svn manual, which is very clearly written. The main chapters of interest are chapters two and three. This manual can be found at http://svnbook.red-bean.com/en/1.0/index.html

Note: During the following, you will be using both an internet browser, a command-line prompt, and possibly a file-browser such as nautilus or konqueror. For convenience, if you are using the KDE desktop environment, you can make the terminal stay on top of other windows by right-clicking on the black bar at the top and selecting 'stay on top'.

Overall Workflow

Terminology

The first time you retrieve a code project from a repository it is called a 'checkout'. After this, when you pull in later changes in a project from the repository these are called 'updates'. The process of sending your own changes away to the repository is called 'committing'. Checking out is something you do only occasionally, when you start a project or if you decide to move your working directory elsewhere on your hard-drive. Committing and Updating are what you will do regularly.

Once you have 'checked out' a project from the repository, then you will use the following processes:

1. edit one of the files in the project using your usual code-editor or IDE.
2. when you are happy with it, use the 'commit' command to send the edited version back to the repository at google.
3. to receive any changes that others have made, you would then use the 'update' command.

Normally, you should do the update first and then the editing and committing steps, to make sure that you can see what changes others have made recently before you begin your own work! However I listed them in this order as it may make a little more sense if this is your very first check-out and you are new to version control. Otherwise you may wonder "Why on Earth am I 'updating' a project if I only just checked it out?!"

Concrete Steps

Installing Subversion

The following install instructions should work for any Debian-related systems, including Ubuntu, Kubuntu, the Computerbank distro, and of course Debian itself. If you are having any difficulties please contact someone for help!

1. Open a terminal
2. Type apt-get install subversion
3. When packages finish loading, in a terminal type svn
4. You should see a message - something like 'type help for usage'. This tells us that Subversion is now installed and available for use.

Checking out our code from the Subversion repository on our Google Project site

Making a spot on your hard-drive to keep the project

Before checking code out of the subversion repository at googlecode, you must first create a space on your hard drive to put the files. The files downloaded will be an exact copy of all the data inside the repository. So even if you only need one file it's best to get this folder ready to save wasted time and effort later.

1. Navigate in a terminal to the area you would like to put the subversion repository
2. mkdir sandbox (sandbox is a traditional name given to a space where experiments are carried out)
3. cd sandbox – this is the place where the project from the google subversion repository will end up.
4. Now follow the steps in the next section to 'checkout' the project.

Using svn to get a copy of the project from the repository at google

First we need to recall the correct command, username, projectname, and password. Rather than trying to remember all this, we can actually just paste it from the 'source' page at our googlecode project on the web.

1. Using an internet browser, log on to our Google project. The project is called 'djangodb', and can be found at the following address: http://code.google.com/p/djangodb
2. Navigate to the 'source' tab.
3. Near the top of the screen is a box containing a command something like

1. You need to copy this entire command, (including the url and your username) into a terminal.
2. If you copy it exactly as above you probably won't get asked for a username, but if you do, give your Google username.
3. When asked for a password, use the special google-subversion password given to you via the link on the 'source' tab of our google project site. Note that this password is not the same as your normal google password. It is specific to the subversion repository. If you have forgotten this password, just click on the link which says 'generated googlecode.com password.' to see it. You must be logged with your normal google password to get it.
4. As the files download onto your computer you will see a long list of the complete files from djangodb. Since this is the first checkout, each one should have an 'A' listed before the filename - this means 'Added'.

Opening and altering a file

The following is an example of what you would do for the 'editing' process listed in the 'overall workflow' section above.

1. For this example, we will edit the readme.txt found in the top-level folder of the project.
2. In a terminal type kate readme.txt This will open the text-editor called 'Kate' and the readme.txt file
3. Add a line to the readme.txt file
4. Save the file
5. Type pwd – 'print working directory' to check where you are located in your terminal. You want to be in the directory where the readme.txt file lives.
6. Type svn status
7. You should see M readme.txt The 'M' means the readme.txt has been modified.

Committing or uploading

The following is an example of what you would do for the 'committing' process listed in the 'overall workflow' section above.

1. In terminal make sure you are inside the djangodb project directory (which we put in the 'sandbox' directory' on your hard drive. Otherwise you will get the message 'not a working svn directory'
2. type svn commit
3. You may be asked for your password and/or username.
4. You should get a confirmation message listing all the files you have just committed.

Other Tasks

Adding a log message

We highly recommend that you give at least a short message each time you commit anything to the repository. This log message should describe briefly what changes you have made and why.

1. hen you are ready to commit, type svn -m <yourmessage> commit <filename>

The text after the -m flag can either be a string typed directly after the -m at the prompt, or, if necessary, the name of a file where you have previously prepared a longer message.

Adding new files and folders

We have covered how to change existing files (that is, files which were already in the repository when you first checked it out). However we have not yet covered how to add new files or folders to the repository.

Adding a new file

1. Create the new file however you usually would - with Kate, with another text-editor, or whatever.
2. Now, from a command prompt in the directory where the new file resides, type

svn add <filename>. This tells svn to schedule this file to be added the next time you commit, but it doesn't actually send anything to the repository yet.

1. Now, in the same directory, type svn commit <filename>. Now the file is actually sent to the repository. You should see an 'A' listed next to its name in the confirmation message svn gives you. This tells you that the file has been 'Added'.

Adding a new directory

1. Unlike with files, you can't create the directory the way you usually would - you must tell svn to create it for you!
2. The command is very close to the usual 'mkdir' command. It is svn mkdir <dirname> As with files, this doesn't actually send the new directory to the repository, it simply schedules it for adding next time you make a commit.
3. Now, in the directory that is the parent of the one you just created (probably this is where you are already), type svn commit. Now the new directory is actually sent to the repository. You should see an 'A' listed next to its name in the confirmation message svn gives you. This tells you that the file has been 'Added'.

Particular problems/errors we have had

Not a working copy?

This next one only applies if you are using kdesvn, a kde specific version of svn. We recommend against this, as although it has some nice features, kdesvn doesn't "play well" with the usual command line svn. kdesvn creates it's own hidden files, and svn detects these and tries to version them. Or vice versa. Or both. Anyway, the main point is that it becomes very confusing, so we have moved away from kdesvn and now only use svn. If you get a message saying you do not have a working copy when you check at kdesvn subversion/workingcopy/update to head Make sure you are at the top of the tree ie at /trunk. If all attempts still gives you a notice saying you do not have a working copy. A workaround for this is to simply create a new folder somewhere on your computer. Open kdesvn in this folder and check out the repository again. Then use this new folder for svn.