TortoiseSVN Daily Use Guide

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.

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 daily use guide. 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 TSVN in our free time.

• It is assumed that you already have installed TortoiseSVN.
• If you're not familiar with Subversion the you should read Version Control with Subversion first.
• If you're stuck, you might also want to take a look at the Subversion or the TortoiseSVN FAQs.

• Terminology
• Creating A Local Repository
• The Repository Browser
• Importing A Project To A New Repository
• Checking Out A Working Copy
• Icon Overlays
• Update Your Working Copy With Changes From Others
• Resolving Conflicts
• Sending Your Changes To The Repository
• Adding New Files And Directories
• Deleting, Renaming And Moving Files
• Cancelling Changes
• Get/Set Information About Files/Directories
• More Info - Revision Log
• Branching / Tagging
• Merging a Branch Back Into The Main Branch
• Relocating a working copy

The terminology used in the SVN documentation, and thus also in TortoiseSVN, may differ from terminology used in other source repository systems. In an attempt to avoid confusion, we provide a short list of the most essential terms. Please make yourself familiar with these words before diving into the rest of this document.

Repository

The big black box in which your valuable data resides, to be automagically retrieved by co-workers anywhere on the planet.
Subversion repositories can be accessed in three ways:

• file:// Anywhere in your local / network filesystem.
• http:// Using Apache 2's WEB_DAV protocol.
• svn:// Using a standalone SVN server with a special protocol.

Module

A directory hierarchy. A software project normally exists as a single module in the repository.

Checkout

Normally used to describe the first retrieval of an entire module from the repository.

Commit

Sending your modifications to the repository.

Export

Refers to extraction of an entire module from the repository, without any SVN administrative files: Exported modules will not be under SVN control.

Import

Normally refers to the process of creating a new module in the repository by sending the entire directory structure.

Working Copy

Your copy of the project on your local harddisk. This is the copy you are working on.

Release

The version of an entire product.

Revision

The version of a complete repository (including branches and tags).

Update

Get other users' modifications from the repository. Updates the local copy only.

If you don't want to create a local repository and use a server based repository instead then you may skip this chapter. You can read a guide on how to set up an apache based repository here

You can easily create a local repository with TortoiseSVN:

1. Open the windows explorer
2. Create a new folder and name it SVNRepository for example
3. Right-click on the folder. Select Create repository here from the TortoiseSVN submenu. Now the repository is created at that location. Don't edit those files yourself! If you get any errors please make sure that the folder is not write protected and empty!

To access your local repository you need the path to that folder. Just remember that Subversion expects all repository paths in the form: file:///SVNRepository/. For Windows users: file:///C:/SVNRepository/.

If you run into trouble accessing a local repository on a network drive, please check the Subversion FAQ.

By clicking on the [...] Button in several TSVN Dialogs, whenever a URL of repository is requested, you can open the TSVN repository browser, to find your repository or files easily.
You have to be aware however, that the [...] Button has two different functions, depending on the context.

• If nothing or an invalid url is enterered, the browser allows you to browse for a local repository inside your filesystem.
• If a valid url is entered, the browser allows you to browse inside the selected repository. See screenshot below.

Before you import your project into a repository you should:

1. Remove all files which are not needed to build the project (temporary files, files which are generated by a compiler e.g. *.obj, compiled binaries, ...)
2. Organize the files in folders and subfolders. Although it is possible to rename/move files later it is highly recommended to get your project's structure straight before importing!
3. The recommended directory structure is as follows:
   

       .../ProjectName/trunk/YourWorkFiles
       .../ProjectName/branches/
       .../ProjectName/tags/
   

That way you can easily create branches and tags later. Please note that this is only a recommendation. You can of course use any other directory structure you want but it might get difficult to organize branches and tags. If you choose this directory layout then TortoiseSVN will warn you if you try to commit to a path in the /tags/ folder.

Now select the parent import folder of your directory structure in the windows explorer and right click to open the context menu. Select the command Import... which brings up a dialog box:

In this dialog you have to enter the URL of the repository into which you want to import your project.

The import message is used as a log message. Since you usually just started your project a default "initial import" is filled in by TortoiseSVN.

As soon as you press the OK button TortoiseSVN imports the complete directory tree including all files into the repository. Please note that this does NOT put your copy of the project under version control yet. To get a versioned working copy you need to do a Checkout of the version you just imported!

The repository structure you just created now looks like this:

    C:/SVNRepository/ProjectName/trunk/All
    C:/SVNRepository/ProjectName/trunk/your
    C:/SVNRepository/ProjectName/trunk/files
    C:/SVNRepository/ProjectName/trunk/are
    C:/SVNRepository/ProjectName/trunk/here
    C:/SVNRepository/ProjectName/trunk/...
    C:/SVNRepository/ProjectName/branches/
    C:/SVNRepository/ProjectName/tags/

If you later want to import C:/myFiles/AnotherProject, organise it in the same way (We recommend putting trunk, branches and tags below the project hierarchy), select C:/SVNRepository/ as URL of repository and import your project. This project is then imported into the following structure:

    C:/SVNRepository/ProjectName/trunk/...
    C:/SVNRepository/ProjectName/branches/
    C:/SVNRepository/ProjectName/tags/
    C:/SVNRepository/AnotherProject/trunk/...
    C:/SVNRepository/AnotherProject/branches/
    C:/SVNRepository/AnotherProject/tags/

To obtain a working copy you need to do a checkout from a repository.

Select a directory in windows explorer where you want to place your working copy. Right-click to pop up the context menu and select the command Checkout... which brings up the following dialog box:

If you enter a folder name that does not yet exist, then a directory with that name is created.

It is recommended that you check out only the "trunk" part of the directory tree. If you specify the parent path of the directory tree in the URL then you might end up with a full harddisk since you will get a copy of each branch and also each tag of your project!

Now that you have checked out a working copy from a Subversion repository you can see your files in the windows explorer with changed icons. TortoiseSVN adds a so called overlay icon to each file icon which overlaps the original file icon. Depending on the Subversion status of the file the overlay icon is different. A fresh checked out working copy has a green checkmark as overlay. that means the Subversion status is normal. As soon as you start editing a file, the status changes to modified and the icon overlay then changes to a red exclamation mark. That way you can easily see which files were changed since you last updated your working copy and need to be commited. If during an update a conflict occurs then the icon changes to a yellow exclamation mark.

The folder icons also have icon overlays displayed. By default, only the status of the folder itself is shown. But you can change that behaviour in the settings (context menu, Settings...) so that the status of folders is shown recursively. This will make the icon overlays for folders slower and is therefore not recommended on slower machines. I'm using that setting on my machine (PIII, 700MHz, 512MB RAM) without problems. With this setting each folder shows the status of all files below it, where status conflict overrides modified and modified overrides normal. So you can easily see if there's a file with a conflict or a modified file in a folder.

Unlike TortoiseCVS (the CVS shell integration) no overlay icon for unversioned files is shown.

Occasionally you may want changes done by others to get incorporated in your local working copy. The process of getting changes from the server to your local copy is known as updating. Updating may be done on single files, a set of selected files, or recursively on entire directory hierarchies. To update, select the files and/or directories you want, right click and select Update in the TortoiseSVN submenu. A window will pop up displaying the progress of the update as it runs.

Changes done by others will be merged into your files, keeping any changes you may have done to the same files. The repository is not affected by an update.

Once in a while, you will get a conflict when you update your files from the repository. A conflict occurs when two or more developers have changed the same few lines of a file. As Subversion knows nothing of your project, it leaves resolving the conflicts to the developers. Whenever a conflict is reported, you should open the file in question, and search for lines starting with the string <<<<<<<. The conflicting area is marked like this:

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


Also, for every conflicted file Subversion places three additional files in your directory:

Here * represents some random digits that Subversion chooses, OLDREV is the revision number of the file in your .svn directory, and NEWREV is the revision number of the repository HEAD.

You can either launch an external merge tool / conflict editor with the Edit Conflict context menu or you can use any other editor to manually resolve the conflict. You should decide what the code should look like and do the necessary changes.

Afterwards execute the command Resolve from the context menu and commit your modifications to the repository. Please note that the Resolve command does not-really™ resolve the conflict. It just removes the filename*.mine and filename*.r* files, to allow you to commit your changes.

Sending the changes you made to your working copy is known as committing the changes. But before you commit you have to make sure that your working copy is up to date. You can either make an update directly. Or you can check for updates first, to see which files have changed locally or on the server.

If your working copy is up to date and you have resolved all conflicts, you are ready to commit your changes. Select any file and/or folders you want to commit and select Commit from the context menu.

The commit dialog will show you every changed file, including added, deleted and unversioned files. If you don't want a changed file to be committed, just uncheck that file. If you want to include an unversioned file, just check that file to add it to the commit.

• include the file into the list of temporary files on the settingspage. This will affect every working copy you have.
• add the file to the svn:ignore list using the ignore context menu. This will only affect the directory on which you set the svn:ignore property. Using the SVN Property Dialog, you can alter the svn:ignore property for a directory.

Doubleclicking on any modified file in the commit dialog will launch the external diff tool to show your changes.

After pressing OK, a dialog appears displaying the progress of the commit.

If you created new files and/or directories during your development process the you need to add them to source control also. Select the file(s) and/or directory and select the command Add from the context menu.

After you added the files/directories to source control the file appears with a "added" icon overlay which means you first have to commit your working copy to make those files/directories available to other developers. Adding a file/directory does not affect the repository!

If you add a directory then TortoiseSVN automatically adds all files in this directory recursively. So be careful with that command and make sure you don't have any temporary or compiler generated files in that directory!

To add files from outside your working copy you can use the drag and drop handler:

1. select the files you want to add
2. right drag them to the new location inside the working copy
3. release the right mouse button
4. in the popup menu select "add files to Subversion". The files will then be copied to the working copy and added to version control.

Unlike CVS, Subversion allows renaming and moving of files. So there are menu entries for delete and rename in the TortoiseSVN submenu.

If you delete a file/directory using TSVN, the file is removed from your working copy and marked from deletion. The file's parent folder shows a "deleted" icon overlay. You can always get the file back, if you call revert on the parent folder.

If you want to move files inside a working copy, use the drag and drop handler again:

1. select the files or directories you want to move
2. right drag them to the new location inside the working copy
3. release the right mouse button
4. in the popup menu select "move files in Subversion to here"

If you want to cancel all changes you made in a file since the last update you need to select the file, right-click to pop up the context menu and then select the command Revert in the TortoiseSVN submenu. But be sure that you really want to do that because all your changes since your last commit will be lost!

If you are not sure about your changes, copy your working directory to a safe location, revert and use a tool that's capable of diffing directories like BeyondCompare or ExamDiff, to see what has happened.

If you accidentally deleted a file and want to get it back without reverting everything, you can commit all changed files inside the directory to the repository and do a revert on the working directory. This will retrieve all files you deleted since your last commit.

Sometimes you want to have a more detailed information about a file/directory than just the icon overlay. You can get all the information Subversion provides in the explorer properties dialog. Just select the file or directory and select "properties" in the context menu (note: this is the normal properties menu entry the explorer provides, not in the TortoiseSVN submenu!). In the properties dialog box TortoiseSVN has added a new property page for files under Subversion control.

On the Subversion page you can see all relevant information about the selected file/directory. In addition you can read and set the subversion properties.

To show the log entries for the selected item simply press "Show Log..." which brings up the revision log dialog.

You can also invoke the Log Dialog from the standard TSVN context menu.

To view a specific log message select the corresponding entry in the list.

Show Log... has a context menu that allows you to:

• Invoke an external diff tool
• Save the selected revision to a file (Export)
• Create a branch or tag of the selected revision
• Revert changes from a specific revision
• Invoke an external unified diff viewer

• You can invoke an external diff tool. This command receives the specific revision of the files and starts an external diff program to show you the differences. By default TortoiseSVN looks for a copy of WinDiff (which comes with the Windows SDK), but you can configure any graphical diff program you want in the TortoiseSVN settings.
• Instead of invoking an external diff tool, you can also request a unified diff. The output of this command is sent to the diff viewer you specified in the settings.

The list of changed files for each log entry can be selected and has it's own context menu. From there it is possible to show the changes which were made to that particular file - either with the external diff program (somewhat slow since two revisions of that file are downloaded) or as a unified diff.

One of the features of version control systems, is the ability to isolate changes onto a separate line of development. This line is known as a branch. Branches are usually used to try out new features without disturbing the main branch of development with compiler errors and bugs. As soon as the new feature of the branch is stable enough then the branch is merged back into the main branch.

Another feature of version control systems is the ability to mark particular revisions (e.g. a release version), so you can at any time recreate a certain build or environment. This proces is known as tagging.

Subversion does not know a special command for branching or tagging. There is a system called cheap copies instead. Cheap copies are something similar to links, which means that no actual copy is made but just a link to a specific file/revision is created.

If you have imported your project with the recommended directory structure creating a branch or tag version is very simple:

Select the parent folder of your working copy and select the command Branch/Tag... from the context menu. Enter the URL to the repository path for branches or tags into the dialog. So instead of /trunk/ you would now use /tags/tagname where tagname would be e.g. "ProjectName_v1.10".

    C:/SVNRepository/trunk/ProjectName/...
    C:/SVNRepository/trunk/AnotherProject/...
    C:/SVNRepository/branches/ProjectName_SpecialDebugBuildBasedOn_v1.09/
    C:/SVNRepository/tags/ProjectName_v1.10

If you press OK now, Subversion just creates a cheap copy of your selected Directory inside the repository. Nothing has happened to your local Disk (yet).

...that is not really the question. While a checkout checks out everything from the desired branch into your working directory, a switch only transfers the changed data to your working copy. Good for the network load, good for your patience. :-)

To be able to work with your freshly generated copy you have several ways to handle it. You can:

• do a Checkout of it again. You can check it out to any location on your local disk and you can create as many working copies from your repository as you like.
• Switch your current working copy to the newly created copy in the repository. Again select the parent folder of your project and select the command Switch... from the context menu.

Here you enter the URL of the branch / tag you just created. Leave the checkbox "newest revision" active. Press ok and your working copy is switched to the new branch / tag.

Only if you modify data, these modifications will be committed to the repository. The rest remains a cheap copy of the original.

From now on working with branches or tags differs a bit:

• If you modify a Tag revision, TortoiseSVN will warn you if you try to commit to a /tags path in the repository. Be aware, that your local files are not write protected. So working on a tag revision is not-a-good-idea™. That's the reason why we recommend the /trunk /branches /tags repository structure in the first place.
• If you modify a working copy created from a branch and commit, then all changes go to the new branch and not the main branch. Only the modifications are stored. The rest remains a cheap copy.

If you want to merge your changes back into the main branch, just select merge from the context menu

• To merge only specific changes from the other branch you have to specify the revisions between which the change occured.
• To merge a complete branch back into the trunk you have to specify the revision the branch was created and HEAD.

If your repository has for some reason changed it's location (IP/URL). Maybe you're even stuck and can't commit and you don't want to checkout your working copy again from the new location and to move all your changed data back into the new working copy, relocate is the command you are looking for. It basically does not much: it scans all "entries" files in the .svn folder and changes the URL of the entries to the new value.

Apart from setting your preferred language, this dialog allows you to specify the

• External Diff Tool (Diff is done by the client)
• External Merge Tool
• External Diff Viewer (Diff is done by Subversion)
• Files patterns to exclude / include from revision control
• Whether to allow adding of unversioned files in a working copy, when the commit dialog is already active

If you like TortoiseSVN and use it often, please support the developers

You can help us by either sending in patches and play an active role in development or you can cheer up the hard working developers.

While working on TortoiseSVN we love to listen to music. And since we work many hours on the project we need a lot of music. Therefore we have set up some wish-lists with our favourite music CD's.

And sometimes we need a break to gather our thoughts, that's why the wish-lists also have some DVD's in it.

The media wish list of Stefan is here (English) or here (Deutsch)

Lübbe has got a wishlist too.

Please have a look at the list of contributors