Using the Syncro Subversion Client

IT Services

Using the Syncro Subversion Client

1. First steps
- 1.1. Obtaining the software, a software key and some OUCS templates
- 1.2. Obtaining a Subversion user account
2. Opening the Syncro SVN Client
3. Connecting to the main Subversion Repository
- 3.1. Creating a Server Repository View
- 3.2. Making a new working copy
- 3.3. Adding your current working directory
4. Working with your files
- 4.1. Updating your files
- 4.2. Open a file for editing
- 4.3. Commiting your changes to the main repository
- 4.4. Adding a new file
- 4.5. Deleting a file
- 4.6. Cancelling changes to files and directories
- 4.7. Obtaining information about files and directories
5. Potential problems
- 5.1. Opening the Syncro Client outside of oXygen
  - 5.1.1. Opening the client on a Mac
- 5.2. Missing icons
- 5.3. File Conflicts
6. Using Syncro Client with OUCS maintained web sites
7. Icons used by the Syncro SVN client

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:

In the Working Copy window find and click on the spanner icon. This opens the Working copies List dialogue.
Click the Add button to open the Add existing working copy dialogue box
Enter some text (that describes your working copy), e.g., ltg-preview, into the Name box
Click on the folders icon to browse to where your working copy is stored
Select your working copy and click on the Open button you will see the path and folder name added to the dialogue box
Click on OK and then click on OK again to complete the process

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:

Navigate to the file you wish to edit on your machine through the Working Copy window
Right click on the file name to open the contextual menu
Select [Update] from the menu
Figure syncroimages/updatefiles.png []
The program will now update your working copy with the one currently in the server repository
The program will tell you if it has updated the file or not
You can now open the file for editing in oXygen

4.2. Open a file for editing

To edit a file in oXygen:

Right click on the file name in the Working Copy window and choose the [Open in <oXygen/>] option
Figure syncroimages/open-oxygen.png []
oXygen will then open and you can edit the file as normal. (There are details about how to do this in the document entitled Using the oXygen XML editor .)
The final stage of your editing will be to save the latest version of the file you have been editing.

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:

Find the file in the Working Copy window of Syncro SVN client
Your changed file should show a * icon. N.B. If you do not see the icon select the folder in the working copy window and press F5. This should force the client to refresh the folder view and the icon should now appear.
Right click on the file to open the contextual menu
Figure syncroimages/commit-menu.png []
Select [Commit] from the options
The Commit dialogue box now opens
Figure syncroimages/commit-dialogue.png []
Make a short note of what you did to the file in the Commit message box
Click on the Commit button
If this is the first time that you have attempted to commit a file back to the repository you will be asked for your SVN password before the file is accepted.
The Console will become active showing that your file is being returned to the server
If you see a box informing you that The file has been changed on the file system, click on the OK button
Go to the preview web site to check your file. If you are happy with the file, you can publish it to the live site directly from the Preview page. (in OUCS this is usually done using the publish button).

Publishing a file

Unless you have special access you can only publish files through the Preview web site.
At the top of the page that needs to be published there are a series of buttons, the most important of which is the red button p-file (means publish file). Click this button to publish the file
A new page appears stating that the file has been committed and that it is now live. You can either return to the preview page or visit the live one via links on this confirmation page

Publishing a directory of files

This is very similar to Publishing a file above but here you publish all files in a directory instead of a single file.
Go to the page which is inside the directory with new pages to publish
Click on the p-dir button (means publish directory) a new page opens listing all the unpublished files in that directory
Decide which files to publish and uncheck any that should not be published
Click the red Make the above changes to the website button
Your files are now published to the live server and are available for viewing
You will see a new page inviting you to return to the preview version of the page or to go and see the live version

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:

Navigate to the folder containing the new file using the Working Copy window of the Syncro SVN client
You will see that the new file has a small ? icon on it. N.B. If you do not see the icon select the folder in the working copy window and press F5. This should force the client to refresh the folder view and the icon should now appear.
Right click on the file to bring up the contextual menu
Figure syncroimages/add-menu.png []
From the menu select [Add]. You will see some activity in the Console window and the overlaying icon on your new file will change to a small + icon
You can now submit this file back to the main Subversion repository. Right click to bring up the contextual menu again and this time select [commit]
The Commit dialogue box appears. State that the file is new and click on the Submit button
The console window will show you that the file is being committed back to the Subversion repository. When complete the file will not have any icons on it, indicating that it is now under subversion control

4.5. Deleting a file

To delete a file:

Navigate to the folder containing the file using the Working Copy window
Highlight the file to be deleted by clicking on it
Press <delete> on your keyboard
You will then be asked to confirm its deletion. Click on Yes if you are sure you wish to delete the file in question
Figure syncroimages/delete-dialogue.png []
The file will now be deleted from your Working Copy
You now need to commit the change back to the Subversion repository. Look at the directory name and you will see the changed icon
Right click on the directory name to open the contextual menu
Select the Commit option
Figure syncroimages/deleted-commit.png []
The Commit dialogue box will open showing you what will happen to the file(s) in the commit. In the example below two files will be deleted.
Figure syncroimages/commit-message.png []
Add in a short message stating what has happened to the file(s) and then click Submit to confirm the action
The file will now be deleted from the main Subversion repository

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:

In the Working copy view go to the directory containing the changed file.
Select the folder and press F5
The folder will now be refreshed and the changed file icon should now appear on both the folder name and the actual file changed.
You can now submit your changed file back to the server.

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:

Right click on the conflicted file to bring up the menu. Select [Edit Conflict] option
Figure syncroimages/edit-conflict.png []
A dialogue box opens which asks you to confirm that you do want to overwrite your conflicted file. Click on OK to continue
Figure syncroimages/conflict2.png []
The two conflicting versions of the file are now opened and can be viewed in the Edit window. The conflicting sections of your file are highlighted in pale red.
Figure syncroimages/conflict-editor.png []
The file on the left is your file while that on the right is the conflicting
To accept the change from the other file you should click on the - icon. The change will be incorporated into your version.
Once you have accepted or not the changes highlighted, press the Save icon
Return to the Working Copy window. The file will still show the conflicting state icon and you will still see the conflicting files listed below it (.rxxxx files). To resolve the conflict, right click on the conflicted file and select [Mark Resolved]. All the .rxxxx files will be removed and your file will now show the changed file icon.
Figure syncroimages/resolved.png []
Commit the file in the usual manner to resolve the conflict

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:

Obtain a Subversion account from the OUCS sysdev team. If you are inside OUCS, you can setup your own account at: https://svn.oucs.ox.ac.uk/admin/useradmin/
Set up a folder called Repository to store your web documents in.
Create a preview folder inside your repository
Download the section of the OUCS web site you need to edit into the preview folder on your local machine
Make your changes to the preview files and upload them back to the main preview repository
View your changes on the preview web site using the following URL format: e.g. http://www.oucs.ox.ac.uk:81/ltg/
Note when trying to view the preview web site outside of the OUCS network you need to use the secure server address https, and add :4443 to the end of the domain name. You will also need to sign in using your SSO account details. The URL in such cases would be: https://www.oucs.ox.ac.uk:4443/ltg/
If you are adding XML files, these are automatically scanned for validity. If there are any problems with the validation of your XML, you will receive an email informing you where the problem is likely to be.
When you are completely happy with your files, publish them to the live site.
Check the web site to see that your changes have taken affect.

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.

IT Services

Using the Syncro Subversion Client

Table of contents