An Eionet Guide to TortoiseSVN Client For Windows.

3.1. Starting TortoiseSVN

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:

[Start] > [Program] > [Windows Explorer]. (N.B. Location varies, try [Accessories] if not in [Program]).

Figure 10. Tortoise menu option and submenu

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 and Checkout. Clicking [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.

Figure 11. Submenu for a new folder

Figure 12. Submenu for a committed folder

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).

3.2. Obtaining a Subversion user account

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:

helpdesk@eionet.europa.eu

3.3. Creating a local working copy of Subversion

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).

Figure 13. Part of the top level Eionet preview directory tree

There are two ways to look at the directory structure.

Use the browse option when Checking out files.

Open the [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 dot icon near the directory pathway text box. Clicking this button opens the browse window.

Using your web browser

Point your web browser at the web site of interest e.g. https://svn.eionet.europa.eu/repositories/Reportnet
(See: Figure 13, Part of the top level Eionet preview directory tree)

3.3.1. Checkout files from the central repository

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:

• https://svn.eionet.europa.eu/repositories/Workdata/
• https://svn.eionet.europa.eu/repositories/Zope
• https://svn.eionet.europa.eu/repositories/Reportnet
• https://svn.eionet.europa.eu/repositories/Biodiversity
• https://svn.eionet.europa.eu/ (- contains list of all repositories)

So if you want to download the Reportnet datadict directory, the URL will be:

https://svn.eionet.europa.eu/repositories/Reportnet/datadict

In the second text box, you need to state how you want the files to be set out in the SVNRepository directory on your machine.

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.

If you are only interested in obtaining the top files in a directory, check the Only check out the top folder box.

Figure 14. Checkout screen showing the email directory path

Click OK to continue. In some versions of the program, the Authentication screen (Figure 15, Authentication screen) will appear.

Figure 15. Authentication screen

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.

Figure 16. The username screen

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).

Figure 17. Downloading files from Subversion to your machine

Figure 18. Email directory structure in the SVNRepository

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.

3.4. 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.

Figure 19. Windows icons overlaid by Subversion icons

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).

Figure 20. Exclamation icon on folder

Figure 21. Red exclamation mark icons on a folder and a html file

3.5. Update your working copy with changes from others

You may wish to incorporate changes in to the document from other users. The process of getting changes from the server to your local copy is called updating.

Figure 22. Using the update command

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.

Figure 23. Updating files in your repository folder

3.6. Committing changes to the central repository

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).

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.

3.7. Resolving file conflicts

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.

(where hello.xml is an example name of your file)

Your file will be marked by a yellow triangle icon:

Figure 25. The file conflict icon

When you encounter a conflict, open the file and find the section which looks like:

<<<<<<< filename
        
        
your changes
code merged from repository
>>>>>>> revision

Subversion also places three additional files in your directory:

• filename.*.mine
• filename.rOLDREV
• filename.*.rNEWREV

The * character represents random figures generated by Subversion.

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.

Figure 26. Conflict resolved screen

3.8. Adding new files and directories

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).

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.

Figure 28. Files or folders to be added to Subversion

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).

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.

Figure 30. Plus overlay icon on a file

3.9. Deleting, moving and renaming files and folders

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.

To move files around your local repository, use the drag and drop method.

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.

Figure 31. Moving files in your local repository

The moved files or folders will have to be added to the repository using the Add and 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).

Figure 32. Newly moved file - without overlay icon

3.10. Canceling changes to files

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.

3.11. 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 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.

Figure 33. Windows Explorer menu

The properties dialog box will appear (Figure 34, Properties dialog box showing the Subversion tab).

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!

Figure 35. Subversion properties dialog box

Figure 36. Log messages dialog box

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).

3.12. Browsing directories with TortoiseSVN

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).

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).

3.13. Reverting files or folders

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).

Figure 38. Submenu showing the revert option

Figure 39. Alert box to confirm revert command

Figure 40. Finished screen showing the reverted file list

3.14. Adding Keywords to your document

The 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:

• Open the Subversion Properties box as described in 3.11. Obtaining information about files and directories.
  
  
  

  Figure 41. Subversion properties box
• Click on the dropdown box and select [svn:keywords]
  
  
  

  Figure 42. Selecting keywords from dropdown menu
• In the bottom textbox add the following keywords:
  LastChangedRevision LastChangedBy Id LastChangedDate HeadURL
  
  
  

  Figure 43. Adding keywords
• Press the Set button, the keywords are added and appear in the upper box.
  
  
  

  Figure 44. Keywords now added to file
  
  
  Click the OK button to complete the process.

Your file will now need to be committed back to Subversion in the usual manner. The document will now show the updated metadata at the foot of the page e.g.

Date: March 2004 (revised Thu, 09 Dec 2004) Author: Ian Senior (revised rahtz).

N.B. If this does not seem to work check that your metadata code is correct. It should look like the following:

<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>