IT Services



Using the Syncro Subversion Client


Table of contents

The XML editor oXygen comes with a built-in SVN client called Syncro SVN Client. This client can be used to send and receive files between your machine and the server. The information team now recommends this as the default method to manage the OUCS web site content.

This guide will show you how to set up the client and use it to manage your section of the OUCS web site.



1. First steps



1.1. Obtaining the software, a software key and some OUCS templates

The first step is to obtain oXygen Editor, a license key for oXygen, and the OUCS setup. The details of how to do this are covered in the document Using the oXygen XML Editor.



1.2. Obtaining a Subversion user account

You will need to get a user account before you can submit files to the Subversion Repository. If you don't yet have a username and password, go to the following web page where you can set up an account: https://svn.oucs.ox.ac.uk/admin/useradmin/

Please note you will be taken to Webauth first to verify your status. Log into Webauth using your Herald email username and password. Once you have an account you can then add and checkout files from Subversion.



2. Opening the Syncro SVN Client

After you have installed and opened oXygen you can access the Syncro SVN client from within oXygen by clicking on [Tools] > [SVN Client].

Figure syncroimages/toolsmenu.png [Tools menu]

The program will now open and you will see the following interface:

Figure syncroimages/synco-interface.png [Syncro SVN interface]



3. Connecting to the main Subversion Repository

Before you can start working on your files you need to connect to the server and download the appropriate section of the OUCS web site.



3.1. Creating a Server Repository View

To connect your client to the main repository:

Open the Syncro SVN client

From the Repository window click on the barrel+ icon:

Figure syncroimages/new-rep-icon.png []

This will open the Add SVN Repository dialogue box:

Figure syncroimages/new-repository.png []

You now need to add the URL to the preview web server. The address is: https://svn.oucs.ox.ac.uk/sites/www.oucs.ox.ac.uk/preview/

Click the OK button. A Certificate Information window will open showing you the server certificate shown below.

Figure syncroimages/certificate.png []

Click on the Accept this certificate permanently radio button to continue. Then click on OK. You will then be asked to authenticate yourself using your SVN account details. Once done you will see that the preview repository has been added to the Repository window of the client.

Figure syncroimages/repository-added.png []

You can view the top level folders on the preview server by clicking on the + button next to the repository url. This will open up a tree view of the OUCS preview site on the server. It may take some time to do this.

Figure syncroimages/open-preview-listing.png []



3.2. Making a new working copy

You now need to download the section of the web site you want to work on i.e. make a working copy. If you already have a working copy of the web site you want to work on, go to 3.3. Adding your current working directory.

In order to download the contents of a directory go to the Repository window. Use the tree view to navigate to the top level section of the OUCS site that you want to download to your machine e.g. about or ltg etc. sections.

Right click on the directory name or press the icon of barrel with a green arrow on it:

Figure syncroimages/checkout-barrel-icon.png []

Either way a new menu appears from which you choose the [Checkout] option.

Figure syncroimages/checkout1.png []

Next the Checkout dialogue box appears which already contains the url of the chosen folder.

Figure syncroimages/url-input.png []

Now click on the Browse button and navigate to where you want to store the folder and files. We recommend that you have a folder named Repository and that you store all your web documents in the same file structure you see on the main server. So it would be best to create a skeleton structure starting from the top of the OUCS tree that leads down to the directory you want to check out.

Click the OK button to start downloading your chosen section. If you now open the Console window (if its not already open), you will see messages appearing there showing you that the client is working. When all of the files have been downloaded the Working Copy window of the client will show your new downloaded files. These can now be opened for editing.

Figure syncroimages/files-checked-out.png []



3.3. Adding your current working directory

If you already have a working copy of part or all of the OUCS web site on your machine, you can make Syncro SVN client see and use this instead of starting a fresh download. To use a working copy of the preview web site:

It may take some time for the Syncro client to update: it depends on how big your working copy is.



4. Working with your files

If you have already used TortoiseSVN, you will find the workflow associated with using Syncro SVN to be similar to that of TortoiseSVN. So in brief:

When you want to start work on a file you must remember to update your copy of a file before you start to work on it. If you forget to do this you may find that your copy is out of date and causes you to have a conflict between your revised copy and that found on the server. Please remember to update your working files before you start work!

Once you have finished working on a file, you should immediately return your revised version to the main repository. This will allow you to see your work on the preview web site.

The URL to do so is:

http://www.oucs.ox.ac.uk:81/folder name/filename .xml

For instance this document has a preview version found at:
http://www.oucs.ox.ac.uk:81/oucsweb/syncroclient.xml

You can also see our preview server when you are out of the building by using the secure version. So for the preview version of this document you would go to:

https://www.oucs.ox.ac.uk:4443/oucsweb/syncroclient.xml
(note the https and changed port number of 4443).

Exactly how to manage, edit, update etc your files is explained in more detail in the next few sections.



4.1. Updating your files

Before you start work on a file it is very good practice to update your working copy by synchronising with the main SVN repository. This will ensure that you have the very latest version of a given file on which to work, and reduces the chances of file conflict upon its return to the main repository.

To update your working copy using Syncro SVN client:



4.2. Open a file for editing

To edit a file in oXygen:



4.3. Commiting your changes to the main repository

The final part of the process is to return your changed file back to the server:

Publishing a file

Publishing a directory of files



4.4. Adding a new file

Sometimes you will want to add a new document to Subversion to be displayed on the web site. This is achieved by:



4.5. Deleting a file

To delete a file:



4.6. Cancelling changes to files and directories

If you want to cancel all your changes since the last file update you need to select the file, right click to bring up the context menu and select [Revert] in the submenu. All your changes will be lost and the file is reverted.

Figure syncroimages/revert.png []



4.7. Obtaining information about files and directories

There are occasions when you need more information about a particular file or directory. This information is available through the Properties dialog. Hover your mouse over the name of a file and you will see a pop-up box with information about the file. This includes the last change author, date of change, state of the file, etc.

Figure syncroimages/file-info.png []



5. Potential problems



5.1. Opening the Syncro Client outside of oXygen

On Windows systems you will find that after installation of oXygen onto your machine you can access the Syncro SVN client through the programs menu ([Start] > [Programs] > [Oxygen XML Editor 10] > [Syncro SVN Client]). It appears that starting the program from here is completely independent of starting it through oXygen itself. If you set up your working copy as described in this document, you will not be able to see this when starting the program through the standard Windows [Start] > [Programs] route.

Figure syncroimages/syncroclients.png []



5.1.1. Opening the client on a Mac

This is identical to the method outlined in section 2. Opening the Syncro SVN Client above. However, the Mac user can also add the application to the dock area by finding the application and dragging to the dock. Opening the client via the dock area is equivalent to starting the application from the Windows Start menu. Clients opened from the dock are independent of those started from within oXygen itself. Any repositories setup will only be available to you if you open the client in the same way each time.



5.2. Missing icons

Sometimes the client does not refresh the working copies folder view when a change has occurred e.g. file added or changed in some way. To force a refresh:



5.3. File Conflicts

Occasionally you may edit a file without first updating it. In many instances this will not be a problem, even if there is a newer version of the same file in the main repository. Often Subversion can merge the different files together. However, occasionally both the file in main repository and your own modified file can conflict with each other due to edits occurring at the same place in the file. This results in your file being rejected. You will also see that there are two .rxxxx versions of the file sent back to you and that the icon overlay has changed to being a small c.

Figure syncroimages/conflict.png []

If this is the case the easiest method to deal with the conflict is to revert your file which will remove your edits, then update the file with the one from the main repository. Finally making your edits again before submitting back to the main repository. This is much the easiest way even if you have made several edits.

However, if instead you wish to sort out the conflicts, you should first compare the files. To do this:



6. Using Syncro Client with OUCS maintained web sites

When using Syncro Client to manage web sites maintained by the OUCS Information Services Group, we recommend the following work practices:



7. Icons used by the Syncro SVN client

In the same way that TortoiseSVN used icons to indicate the state of your local files, Syncro SVN also uses its own icons. Unfortunately these are very small and only applied to your files when they are viewed using the client itself. Below is a listing of these icons and what they mean as supplied in the Syncro SVN Client help pages. The following information is taken from the Help section of the Syncro SVN Client.

Unversioned

Figure syncroimages/new_icon.png [resource added icon]

The resource marked with this symbol is not under version control. This is how new files are represented when they are created or copied from the file system. Unversioned resources can be filtered from the Working Copy view by setting ignore filters in the Preferences.
Added

Figure syncroimages/added_icon.png [resource added icon]

This resource has been added to version control but has not been committed. This state is obtained after issuing an Add command on an unversioned resource.
Added with history

Figure syncroimages/addhistory_icons.png [resource changed icon]

This resource has been copied with history. This state is obtained by copying, moving or renaming a resource from the working copy.
Modified

Figure syncroimages/changed_icon.png [resource changed icon]

The resource has been locally modified since the last update. This is obtained after editing a file and making changes.
Deleted

Figure syncroimages/deleted_icons.png [resource added icon]

This resource has been deleted from the working copy. This state appears after deleting, moving or renaming files with Subversion.
Missing/Incomplete

Figure syncroimages/missing_icons.png [resource missing icon]

This resource is in an inconsistent state. If it's missing, it means it has been deleted from the file system without Subversion's knowledge. If it's incomplete, a check out or update action has probably failed or has been interrupted before finishing. A directory in such a state must be restored with an update action before any other action can be performed.
Conflicted

Figure syncroimages/conflict_icon.png [resource conflicted icon]

This resource has conflicting changes. A resource can be in this state after an update, if it was modified both locally and on the repository and the modifications were overlapping.
External

Figure syncroimages/external_icons.png [externals icon]

This indicates a mapping of a local directory to the URL of a versioned resource. It is declared with a svn:externals property in the parent folder.
Normal

Figure syncroimages/vcontrolled_icon.png [resource under version control icon]

A resource with no overlaid icon is an unmodified resource under version control.
Grayed

Figure syncroimages/greyed_icons.png [ignored resource icon]

A resource with a grayed icon but no overlaid icon is an ignored resource. It is obtained with the action Add to svn:ignore.
Switched

Figure syncroimages/switched_icons.png [switched icon]

This indicates a resource that has been switched from the initial repository location to a new location within the same repository. The resource goes to this state as a result of the Switch action executed from the contextual menu of the Working Copy view.