Using Subversion

Sub-version (SVN) is essentially a central store for a code base, that people can download, alter and put back. Each time an alteration, addition or deletion is made, that 'revision' is saved.

This enables many people to edit the same code base in a collaborative manner. The easiest way of connecting with the SVN repository is through a program called "Tortoise SVN".

Installation of Tortoise

Tortoise can be downloaded from Sourceforge.

It is straightforward to install, although you may need to use the Jaws key command Insert b, to read the text of each dialogue window.

Checkout a Script

The first step to working on a script is to checkout, or download, a working copy.

  • Check the Project Browser and make a note of the script you want to checkout.
  • Go to the folder in Windows Explorer where you'd like to save the working copy of the script. Note, it is good practice to give the folder the same name as the script.
  • Use the Context Menu and select "SVN checkout"....
  • In the dialogue window that appears, enter the path to the project you want to download. For example: http://alastairc.ac/svn/jaws-scripts/project_name/trunk/ . Note, project_name should be changed to the script (or set of scripts) you want to work on.
  • Check the second edit field, to confirm the destination path is correct.
  • The remaining options in the dialogue can be left as default.
  • Press OK, and enter your username and password, possibly twice, to confirm the checkout.
  • A dialogue opens listing information about the script that has been checked out, press OK to complete the process.

Update a Script

You can update the copy of a script you've already checked out.

  • Go to the folder in Windows Explorer where the script files are stored.
  • Use the Context Menu to select "SVN Update".

Trunk, Branches and Tags

Trunk

The main working version of a script, the one that will be continually developed.

Branches

A variation of the main trunk, that happens when the script branches off in a new direction, for example when a different variation of a script is needed for a new version of Jaws.

Tags

A tagged copy of the script is saved, indicating that a script version number has been completed.

In general, people work on the trunk. A tagged version is saved when a version number is reached, e.g. version 2. Work then continues on the trunk.

Adding, Deleting and Moving

Once you have a working copy, you are ready to start coding. However, if you add a file, delete something, or change it's name, you need to let SVN know.

Note, if Jaws doesn't read the Tortoise SVN menu items correctly, use the Jaws key command, Insert -, to switch to the Jaws cursor, then use the cursor keys to move through the menu items.

Add a file

  • Create the new file in the working directory of the script, or copy a file from a different location.
  • Bring up the Context Menu, move to the Tortoise SVN menu and select "Add".
  • A dialogue opens with the new file listed, press OK to add the file.
  • A dialogue confirming the file has been added appears, press OK to complete the process.

Deleting a file

  • Select the file you want to delete and bring up the Context Menu.
  • Move to the Tortoise SVN menu and select "Delete". Note, if you don't use the Tortoise SVN menu to delete the file, it will reappear when you next update from the repository.

Renaming a file

  • Select the file you want to rename and bring up the Context Menu.
  • Move to the Tortoise SVN menu and select "Rename".
  • Rename the file and press OK to complete the process. Note, if you don't use the Tortoise SVN menu to rename the file, the name change won't be recognised by the repository.

Committing Back To The Repository

When you have made changes to a file, you will need to commit a copy back into the central repository.

Note, if other people could have made changes to the script while you were working on it, it is best to do an "SVN update" first. If someone else has edited the same file, you can then merge the changes together. (More info from the SVN Book merging chapter).

Commiting a single file

  • Select the file you have been working on, bring up the Context Menu, and select "SVN Commit".
  • Add a comment that outlines what changes you have made to the file and press OK to commit the file.
  • A dialogue window opens to confirm the files have been commited, press OK to complete the process.

Commiting a whole script folder

If you have been working on more than one file, it is sometimes easier to commit the script folder in one go.

  • Select the folder where the script files are stored, bring up the Context Menu and select "SVN Commit".
  • Add in a comment that outlines the changes that have been made to the script and press OK to commit the files.
  • A dialogue opens to confirm the files have been commited, press OK to complete the process.

Further Resources

Read the freely available SVN Book. It is the resource for SVN, or Sub-version, which is the application that uses Tortoise as an interface.