Chapter 4. Daily Use Guide

TortoiseSVN

Chapter 4. Daily Use Guide

Table of Contents

4.1. General Features
4.1.1. Icon Overlays
4.1.2. Context Menus
4.1.3. Drag and Drop
4.1.4. Common Shortcuts
4.1.5. Authentication
4.1.6. Maximizing Windows
4.2. Importing Data Into A Repository
4.2.1. Import
4.2.2. Import in Place
4.2.3. Special Files
4.3. Checking Out A Working Copy
4.3.1. Checkout Depth
4.3.1.1. Sparse Update using Update to Revision
4.3.1.2. Sparse Update using Repo Browser
4.3.1.3. Sparse Update using Check for Modifications
4.4. Committing Your Changes To The Repository
4.4.1. The Commit Dialog
4.4.2. Change Lists
4.4.3. Commit only parts of files
4.4.4. Excluding Items from the Commit List
4.4.5. Commit Log Messages
4.4.6. Commit Progress
4.5. Update Your Working Copy With Changes From Others
4.6. Resolving Conflicts
4.6.1. File Conflicts
4.6.2. Property Conflicts
4.6.3. Tree Conflicts
4.6.3.1. Local delete, incoming edit upon update
4.6.3.2. Local edit, incoming delete upon update
4.6.3.3. Local delete, incoming delete upon update
4.6.3.4. Local missing, incoming edit upon merge
4.6.3.5. Local edit, incoming delete upon merge
4.6.3.6. Local delete, incoming delete upon merge
4.6.3.7. Other tree conflicts
4.7. Getting Status Information
4.7.1. Icon Overlays
4.7.2. Detailed Status
4.7.3. Local and Remote Status
4.7.4. Viewing Diffs
4.8. Change Lists
4.9. Revision Log Dialog
4.9.1. Invoking the Revision Log Dialog
4.9.2. Revision Log Actions
4.9.3. Getting Additional Information
4.9.4. Getting more log messages
4.9.5. Current Working Copy Revision
4.9.6. Merge Tracking Features
4.9.7. Changing the Log Message and Author
4.9.8. Filtering Log Messages
4.9.9. Statistical Information
4.9.9.1. Statistics Page
4.9.9.2. Commits by Author Page
4.9.9.3. Commits by date Page
4.9.10. Offline Mode
4.9.11. Refreshing the View
4.10. Viewing Differences
4.10.1. File Differences
4.10.2. Line-end and Whitespace Options
4.10.3. Comparing Folders
4.10.4. Diffing Images Using TortoiseIDiff
4.10.5. Diffing Office Documents
4.10.6. External Diff/Merge Tools
4.11. Adding New Files And Directories
4.12. Copying/Moving/Renaming Files and Folders
4.13. Ignoring Files And Directories
4.13.1. Pattern Matching in Ignore Lists
4.14. Deleting, Moving and Renaming
4.14.1. Deleting files and folders
4.14.2. Moving files and folders
4.14.3. Dealing with filename case conflicts
4.14.4. Repairing File Renames
4.14.5. Deleting Unversioned Files
4.15. Undo Changes
4.16. Cleanup
4.17. Project Settings
4.17.1. Subversion Properties
4.17.1.1. svn:keywords
4.17.1.2. Adding and Editing Properties
4.17.1.3. Exporting and Importing Properties
4.17.1.4. Binary Properties
4.17.1.5. Automatic property setting
4.17.2. TortoiseSVN Project Properties
4.17.3. Property Editors
4.17.3.1. External Content
4.17.3.2. SVN Keywords
4.17.3.3. EOL Style
4.17.3.4. Issue Tracker Integration
4.17.3.5. Log Message Sizes
4.17.3.6. Project Language
4.17.3.7. MIME-type
4.17.3.8. svn:needs-lock
4.17.3.9. svn:executable
4.17.3.10. Merge log message templates
4.18. External Items
4.18.1. External Folders
4.18.2. External Files
4.18.3. Creating externals via drag and drop
4.19. Branching / Tagging
4.19.1. Creating a Branch or Tag
4.19.2. Other ways to create a branch or tag
4.19.3. To Checkout or to Switch...
4.20. Merging
4.20.1. Merging a Range of Revisions
4.20.2. Merging Two Different Trees
4.20.3. Merge Options
4.20.4. Reviewing the Merge Results
4.20.5. Merge Tracking
4.20.6. Handling Conflicts during Merge
4.20.7. Feature Branch Maintenance
4.21. Locking
4.21.1. How Locking Works in Subversion
4.21.2. Getting a Lock
4.21.3. Releasing a Lock
4.21.4. Checking Lock Status
4.21.5. Making Non-locked Files Read-Only
4.21.6. The Locking Hook Scripts
4.22. Creating and Applying Patches
4.22.1. Creating a Patch File
4.22.2. Applying a Patch File
4.23. Who Changed Which Line?
4.23.1. Blame for Files
4.23.2. Blame Differences
4.24. The Repository Browser
4.25. Revision Graphs
4.25.1. Revision Graph Nodes
4.25.2. Changing the View
4.25.3. Using the Graph
4.25.4. Refreshing the View
4.25.5. Pruning Trees
4.26. Exporting a Subversion Working Copy
4.26.1. Removing a working copy from version control
4.27. Relocating a working copy
4.28. Integration with Bug Tracking Systems / Issue Trackers
4.28.1. Adding Issue Numbers to Log Messages
4.28.1.1. Issue Number in Text Box
4.28.1.2. Issue Numbers Using Regular Expressions
4.28.2. Getting Information from the Issue Tracker
4.29. Integration with Web-based Repository Viewers
4.30. TortoiseSVN's Settings
4.30.1. General Settings
4.30.1.1. Context Menu Settings
4.30.1.2. TortoiseSVN Dialog Settings 1
4.30.1.3. TortoiseSVN Dialog Settings 2
4.30.1.4. TortoiseSVN Dialog Settings 3
4.30.1.5. TortoiseSVN Colour Settings
4.30.2. Revision Graph Settings
4.30.2.1. Revision Graph Colors
4.30.3. Icon Overlay Settings
4.30.3.1. Icon Set Selection
4.30.3.2. Enabled Overlay Handlers
4.30.4. Network Settings
4.30.5. External Program Settings
4.30.5.1. Diff Viewer
4.30.5.2. Merge Tool
4.30.5.3. Diff/Merge Advanced Settings
4.30.6. Saved Data Settings
4.30.7. Log Caching
4.30.7.1. Cached Repositories
4.30.7.2. Log Cache Statistics
4.30.8. Client Side Hook Scripts
4.30.8.1. Issue Tracker Integration
4.30.9. TortoiseBlame Settings
4.30.10. TortoiseUDiff Settings
4.30.11. Exporting TSVN Settings
4.30.12. Advanced Settings
4.31. Final Step

This document describes day to day usage of the TortoiseSVN client. It is not an introduction to version control systems, and not an introduction to Subversion (SVN). It is more like a place you may turn to when you know approximately what you want to do, but don't quite remember how to do it.

If you need an introduction to version control with Subversion, then we recommend you read the fantastic book: Version Control with Subversion .

This document is also a work in progress, just as TortoiseSVN and Subversion are. If you find any mistakes, please report them to the mailing list so we can update the documentation. Some of the screenshots in the Daily Use Guide (DUG) might not reflect the current state of the software. Please forgive us. We're working on TortoiseSVN in our free time.

In order to get the most out of the Daily Use Guide:

  • You should have installed TortoiseSVN already.

  • You should be familiar with version control systems.

  • You should know the basics of Subversion.

  • You should have set up a server and/or have access to a Subversion repository.

4.1. General Features

This section describes some of the features of TortoiseSVN which apply to just about everything in the manual. Note that many of these features will only show up within a Subversion working copy.

4.1.1. Icon Overlays

Figure 4.1. Explorer showing icon overlays

Explorer showing icon overlays

One of the most visible features of TortoiseSVN is the icon overlays which appear on files in your working copy. These show you at a glance which of your files have been modified. Refer to Section 4.7.1, “Icon Overlays” to find out what the different overlays represent.

4.1.2. Context Menus

Figure 4.2. Context menu for a directory under version control

Context menu for a directory under version control


All TortoiseSVN commands are invoked from the context menu of the windows explorer. Most are directly visible, when you right click on a file or folder. The commands that are available depend on whether the file or folder or its parent folder is under version control or not. You can also see the TortoiseSVN menu as part of the Explorer file menu.

[Tip] Tip

Some commands which are very rarely used are only available in the extended context menu. To bring up the extended context menu, hold down the Shift key when you right click.

In some cases you may see several TortoiseSVN entries. This is not a bug!

Figure 4.3. Explorer file menu for a shortcut in a versioned folder

Explorer file menu for a shortcut in a versioned folder


This example is for an unversioned shortcut within a versioned folder, and in the Explorer file menu there are three entries for TortoiseSVN. One is for the folder, one for the shortcut itself, and the third for the object the shortcut is pointing to. To help you distinguish between them, the icons have an indicator in the lower right corner to show whether the menu entry is for a file, a folder, a shortcut or for multiple selected items.

4.1.3. Drag and Drop

Figure 4.4. Right drag menu for a directory under version control

Right drag menu for a directory under version control


Other commands are available as drag handlers, when you right drag files or folders to a new location inside working copies or when you right drag a non-versioned file or folder into a directory which is under version control.

4.1.4. Common Shortcuts

Some common operations have well-known Windows shortcuts, but do not appear on buttons or in menus. If you can't work out how to do something obvious, like refreshing a view, check here.

F1

Help, of course.

F5

Refresh the current view. This is perhaps the single most useful one-key command. For example ... In Explorer this will refresh the icon overlays on your working copy. In the commit dialog it will re-scan the working copy to see what may need to be committed. In the Revision Log dialog it will contact the repository again to check for more recent changes.

Ctrl-A

Select all. This can be used if you get an error message and want to copy and paste into an email. Use Ctrl-A to select the error message and then ...

Ctrl-C

Copy the selected text. In case no text is selected but e.g. a list entry or a message box, then the content of that list entry or the message box is copied to the clipboard.

4.1.5. Authentication

If the repository that you are trying to access is password protected, an authentication Dialog will show up.

Figure 4.5. Authentication Dialog

Authentication Dialog


Enter your username and password. The checkbox will make TortoiseSVN store the credentials in Subversion's default directory: %APPDATA%\Subversion\auth in three subdirectories:

  • svn.simple contains credentials for basic authentication (username/password). Note that passwords are stored using the WinCrypt API, not in plain text form.

  • svn.ssl.server contains SSL server certificates.

  • svn.username contains credentials for username-only authentication (no password needed).

If you want to clear the authentication cache, you can do so from the Saved Data page of TortoiseSVN's settings dialog. The button Clear all will clear the cached authentication data for all repositories. The button Clear... however will show a dialog where you can chose which cached authentication data should be deleted. Refer to Section 4.30.6, “Saved Data Settings”.

Some people like to have the authentication data deleted when they log off Windows, or on shutdown. The way to do that is to use a shutdown script to delete the %APPDATA%\Subversion\auth directory, e.g.

@echo off
rmdir /s /q "%APPDATA%\Subversion\auth"
      

You can find a description of how to install such scripts at http://www.windows-help-central.com/windows-shutdown-script.html .

For more information on how to set up your server for authentication and access control, refer to Section 3.5, “Accessing the Repository”.

4.1.6. Maximizing Windows

Many of TortoiseSVN's dialogs have a lot of information to display, but it is often useful to maximize only the height, or only the width, rather than maximizing to fill the screen. As a convenience, there are shortcuts for this on the Maximize button. Use the middle mouse button to maximize vertically, and right mouse to maximize horizontally.