Eionet has changed the document management system responsible for storing and delivering our documentation across the network and web. The main software is now Subversion, a powerful open source document change program. In order to use this system, Windows users will need to obtain and install a client application. One such client is TortoiseSVN, a GUI (graphical interface) program designed for Subversion. It is through TortoiseSVN that Windows users interact with Subversion. This document outlines how to setup TortoiseSVN and use the program with Subversion.
TortoiseSVN home page is at: http://tortoisesvn.tigris.org/
The TortoiseSVN developers have now dropped support for older Windows operating software. If you need to use TortoiseSVN on Windows 95/98/Me/NT4 then you will have to use an archived version instead. The last supported version was 1.1.7. See the TortoiseSVN archive for this release.
Please be aware that the version number in the file will change as they release newer versions. You should always obtain the latest stable version that is available from the site. This document was based on version 0.19 of the software running on Windows 2000 and procedures may be different in later versions or different platforms.
Download the file to your computer and double click the
installer icon to begin the installation. The welcome screen will open (Figure 2, Welcome screen of TortoiseSVN), click the
Next button to continue.
Once closed the program will continue to install TortoiseSVN and you will see the
Installing TortoiseSVN screen. Followed by the
Installation Complete screen (Figure 8, Installation complete screen). Click the
Close button to exit the installation program. TortoiseSVN has now been installed on to your machine.
Installation of TortoiseSVN on to your computer does not result in the program being present in the programs list or as an icon on the desktop. Instead TortoiseSVN appears as an additional menu option within
Windows Explorer. To check that the program has being installed correctly, open Windows Explorer:
Once Windows Explorer is running, select
[File] from the top menu bar and in the drop down menu you will see an entry for
[TortoiseSVN] option brings up the submenu (Figure 10, Tortoise menu option and submenu). Once you have checked out files from the central Subversion repository, you will be able to add, delete or edit your locally held documents and submit them back to the central Subversion repository.
Please note. The items in the TortoiseSVN submenu change depending on what you are trying to do. Selecting a folder that has not been added to your local repository for instance produces a submenu such as (Figure 11, Submenu for a new folder), while one that is already submitted to Subversion produces one as in (Figure 12, Submenu for a committed folder).
You can usually checkout files from Subversion anonymously, but to checkin, you will need to get a user account. If you don't yet have a username and password, email the helpdesk and ask them to set up an Eionet account:
Before any document can be accessed, the correct path to the Subversion directory has to be set. This is achieved through the TortoiseSVN submenu. First of all you should make a new folder on your hard disc and name it
SVNRepository. This is where you will store local copies of documents from Subversion.
Most users of TortoiseSVN will only want to access a subset of Eionet web pages or documents. To be able to do this, you need to know where your pages are within the directory structure (See: Figure 13, Part of the top level Eionet preview directory tree).
[TortoiseSVN]submenu and click on the
[Checkout]option. This will open the
Checkout box(Figure 14, Checkout screen showing the email directory path). The browse option is indicated by the
three doticon near the directory pathway text box. Clicking this button opens the browse window.
Select the SVNRepository folder using Windows Explorer, open the
[TortoiseSVN] menu and click the
[Checkout] option. The
Checkout screen will open (Figure 14, Checkout screen showing the email directory path). On the
Checkout screen, enter the URL to the directory containing your files. The main sites are given below:
To download only the datadict tree for instance, your checkout directory path should be
datadict (provided you are in the SVNRepository folder to start with). Similarly if you wish to only download the webrod section you should type
webrod. All files and folders under the specified directory, e.g. webrod, will be copied to your computer.
OK to continue. In some versions of the program, the
Authentication screen (Figure 15, Authentication screen) will appear.
Type in your password here. Click
OK. At the next screen (Figure 16, The username screen) type in your username and again click
OK. These two security screens only appear the first time you download files from the central Subversion system.
Your files will then be downloaded to your local repository (Figure 17, Downloading files from Subversion to your machine). When file download is complete, click
OK to close the
finished screen (not shown).
Open your SVNRepository to see the downloaded files. You will see the directory structure that you specified in the checkout directory box (Figure 14, Checkout screen showing the email directory path).
Folder and file icons have been replaced with special
Subversion ones (Figure 18, Email directory structure in the SVNRepository). See the next section for further details about these icons.
TortoiseSVN overlays normal Windows icons with those of its own. These icons show the user the state of their files compared to those in the central repository. A fresh download of files from the central repository will show files with the
green tick icon overlaying the Windows. This can be seen in Figure 19, Windows icons overlaid by Subversion icons. If you cannot see these icons try restarting your machine.
When you have edited a file in the local repository, the icon will change from the
green tick to a
red exclamation mark. This allows you to see which documents are being worked on and that they will need to be committed back to the main server. If during an update a conflict occurs the icon changes to a
yellow exclamation mark (see Figure 25, The file conflict icon).
In order to update your local files with changes from other users, select the files or folders you want, right click and select
[update] from the menu (Figure 22, Using the update command). A window will appear showing you the progress of the update (Figure 23, Updating files in your repository folder). All changes from other users will be merged into your own.
Once editing has been completed, your changes need to be submitted back to the central Subversion repository. This is called
Committing the changes. The procedure requires that your file is up-to-date prior to committing your changes. Right click on the file or directory in question and select
[update] from the menu (see Figure 22, Using the update command). Any changes to the document that have been made by other users will now be incorporated into your own edits. It is at this point that you may encounter conficts between your file and the one held centrally. See resolving file conflicts for further information.
Once your files and folders are fully updated and any conflicts have been resolved, you can then commit your files to the repository. Select
[commit] from the menu (Figure 24, Selecting the commit option from the menu).
The commit dialog will show all changes made to your files. If you do not want a particular change to be committed uncheck the corresponding box. After pressing
OK, you may be asked to enter your username and password. Once these are authorised, your files are saved to the central Subversion repository.
Occasionally you will encounter a conflict between your file and someone else's. This occurs when 2 people have altered the same lines in the document. Subversion cannot resolve such issues and leaves it up to you.
A conflict between files is indicated by TortoiseSVN during the commit procedure. If your version of the file conflicts with a version already on the central repository, TortoiseSVN will show an error message:
Commit failed (details follow) Your file hello.xml is probably out of date. The version resource does not correspond to the resource within the transaction.
<<<<<<< filename your changes code merged from repository >>>>>>> revision
You need to decide what the text or code should be and make the appropriate changes. Once editing is completed use the command
[Resolve] from the submenu to commit your changes back to the Subversion repository. You will then see your file added to the central repository and the following screen displayed (Figure 26, Conflict resolved screen). The conflict icon on the file will change to the
green tick indicating that the file has been accepted and is now in sync with the central repository.
All new files and folders need to be added to the main repository. Make sure that the files or folders are located in the SVNRepository folder on your machine. Select the file(s) and/or directory and select
[Add] from the context menu (Figure 27, The add option in the TortoiseSVN submenu).
TortoiseSVN shows you the files it will add to the repository (Figure 28, Files or folders to be added to Subversion), uncheck any that you do not want to add at this point, click
OK to continue.
The files are added to the repository, you will see a list of files that are being added as this process occurs (Figure 29, Files added to the local repository).
After adding, files or directories appear with the
plus icon overlay (Figure 30, Plus overlay icon on a file). This means that the files need to be committed before they are available to other users. You now need to commit the files to the main Subversion system using the commit command as previously described.
To delete a file or folder, select the file or folder to be deleted, then select
[delete] from the submenu. A confirmation screen will appear, click
Yes to delete the file. The file is removed from your local repository and marked for deletion. You can get the file back by performing a revert on the parent folder.
Select the files or directories you want to move, click on the right mouse button and drag the items to their new location and release the mouse button. A pop up menu will appear (see Figure 31, Moving files in your local repository). Select
[Move Here] option from the menu to complete the move.
The moved files or folders will have to be added to the repository using the
Commit commands in the usual way. This is indicated by the lack of the
green tick on the
file icon (Figure 32, Newly moved file - without overlay icon).
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 Explorer
Properties dialog. Select the file or directory and right click to bring up the
[Explorer] menu. The last option on the list is
[Properties] (Figure 33, Windows Explorer menu), click on this option.
The properties dialog box will appear (Figure 34, Properties dialog box showing the Subversion tab).
One of the tabs on this screen is called
Subversion, click this tab to open
Subversion properties box (Figure 35, Subversion properties dialog box). Information about the file or directory is shown on this page. There is also an option to see the file's log. Click on
show log... to see the log file. Information supplied by the editors of the file or directory is displayed (Figure 36, Log messages dialog box). This can take a while to appear so be patient!
To view comments made by the file's editor, select one of the revision entries in the list. Comments added by the editor will appear in the box below the revision list. This dialog box is also accessible through the
[TortoiseSVN] submenu. It is listed as
Show log (Figure 12, Submenu for a committed folder).
After the first time you have checked out files from the central repository, you will be able to browse through the tree to locate other files/folders for download. To browse for folders, select the
[Checkout] option from the TortoiseSVN submenu. You will then see the
Checkout screen (Figure 14, Checkout screen showing the email directory path). Click the
3 dots button to the side of the URL path text box. A new screen will open showing you the files that you have already downloaded. If you double click on the main directory name, the screen will refresh and display the directory tree from the central repository (Figure 37, Browsing the central Subversion repository).
Click on a folder to show the contents. This will also alter the URL in the text box. If you want to checkout a directory, select it and click
OK. The directory URL will be copied over to the
Checkout screen. If you do not want to copy over the URL, press
Cancel to return to the
Checkout screen (without the URL being copied).
Occasionally you may want to revert a file back to the version held on the main repository. Right click on the file and select
[Revert] from the submenu (Figure 38, Submenu showing the revert option). You will see an alert box (Figure 39, Alert box to confirm revert command) asking you to confirm the revert command. Click
OK to continue. The file will be reverted back to the version held in the main repository and you will see the
Finish screen (Figure 40, Finished screen showing the reverted file list).
Subversion Properties box is also important for setting the change date metadata for the file. Metadata is information about the file e.g. when it was created and by whom. If the file was made from a copy of another, the metadata will not be properly updated. It is necessary to add keywords to the file through
Subversion Properties. To add keywords to the file:
Subversion Propertiesbox as described in 3.11. Obtaining information about files and directories.
LastChangedRevision LastChangedBy Id LastChangedDate HeadURL
Setbutton, the keywords are added and appear in the upper box.
OKbutton to complete the process.
<revisionDesc> <change> <date>$Date: 2005-12-08 10:37:23 +0000 (Thu, 08 Dec 2005) $$</date> <respStmt> <name>$Author: ian $</name> </respStmt> <item>$Revision: 36150 $</item> </change> </revisionDesc>