Table of contents
- 1. First steps
- 2. Opening the Syncro SVN Client
- 3. Connecting to the main Subversion Repository
- 4. Working with your files
- 5. Potential problems
- 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.
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.
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.
Webauth using your Herald email username and password. Once you
have an account you can then add and checkout files from Subversion.
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.
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
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.
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
OKbutton to start downloading your chosen section. If you now open the
Consolewindow (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 Copywindow of the client will show your new downloaded files. These can now be opened for editing.
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 Copywindow find and click on the
spannericon. This opens the
Working copies Listdialogue.
- Click the
Addbutton to open the
Add existing working copydialogue box
- Enter some text (that describes your working copy), e.g.,
ltg-preview, into the
- Click on the
foldersicon to browse to where your working copy is stored
- Select your working copy and click on the
Openbutton you will see the path and folder name added to the dialogue box
- Click on
OKand then click on
OKagain to complete the process
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!
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.
- Navigate to the file you wish to edit on your machine through the
- Right click on the file name to open the contextual menu
[Update]from the menu
- 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
- Right click on the file name in the
Working Copywindow and choose the
[Open in <oXygen/>]option
- 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.
- Find the file in the
Working Copywindow 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
[Commit]from the options
Commitdialogue box now opens
- Make a short note of what you did to the file in the Commit message box
- Click on the
- 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.
Consolewill 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
- 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-dirbutton (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 websitebutton
- 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
- Navigate to the folder containing the new file using the
Working Copywindow 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
- From the menu select
[Add]. You will see some activity in the
Consolewindow and the overlaying icon on your new file will change to a small
- 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
Commitdialogue box appears. State that the file is new and click on the
consolewindow 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
- Navigate to the folder containing the file using the
- Highlight the file to be deleted by clicking on it
<delete>on your keyboard
- You will then be asked to confirm its deletion. Click on
Yesif you are sure you wish to delete the file in question
- The file will now be deleted from your
- You now need to commit the change back to the Subversion repository. Look at the
directory name and you will see the
- Right click on the directory name to open the contextual menu
- Select the Commit option
Commitdialogue box will open showing you what will happen to the file(s) in the commit. In the example below two files will be deleted.
Submitto confirm the action
- The file will now be deleted from the main Subversion repository
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.
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.
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 (
[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
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.
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.
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.
- Right click on the conflicted file to bring up the menu. Select
- A dialogue box opens which asks you to confirm that you do want to overwrite your
conflicted file. Click on
- The two conflicting versions of the file are now opened and can be viewed in the
Editwindow. The conflicting sections of your file are highlighted in pale red.
- 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
- Return to the
Working Copywindow. 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.
- Commit the file in the usual manner to resolve the conflict
- 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
Repositoryto store your web documents in.
- Create a
previewfolder 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.
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
:4443to 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:
- 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.
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.
- 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.
- This resource has been added to version control but has not been committed.
This state is obtained after issuing an
Addcommand on an unversioned resource.
- Added with history
- This resource has been copied with history. This state is obtained by copying, moving or renaming a resource from the working copy.
- The resource has been locally modified since the last update. This is obtained after editing a file and making changes.
- This resource has been deleted from the working copy. This state appears after deleting, moving or renaming files with Subversion.
- 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.
- 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.
- This indicates a mapping of a local directory to the URL of a versioned
resource. It is declared with
a svn:externalsproperty in the parent folder.
- A resource with no overlaid icon is an unmodified resource under version control.
- A resource with a grayed icon but no overlaid icon is an ignored resource. It
is obtained with the action
Add to svn:ignore.
- 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
Switchaction executed from the contextual menu of the Working Copy view.