Using TortoiseSVN for Subversion

This tutorial aims to provide fast paced instructions to use TortoiseSVN as an SVN client

Introduction to TortoiseSVN

There are a lot of tutorials that will explain how to use a Subversion client to access a Subversion repository, this is just another one of them.
I just got a bit tired of having to explain the all usage over and over again, that said, this tutorial will focus on TortoiseSVN, a Subversion client for Windows, other client are not mentioned but the operations are the same, only the way you access them is different.

I will not cover the installation process of TortoiseSVN, it is as straight forward as any windows application, just execute the installer and follow the wizard's instructions. Please note that TortoiseSVN installation requires you to restart you windows machine at the end, you can't use it before you restart.

Needed tools for this tutorial

As this tutorial is focusing on TortoiseSVN you will need to get it from here
It's the only tool you will need for the tutorial, other than a Windows installation ;)

Using TortoiseSVN

TortoiseSVN is not your usual graphical application, you will have no shortcut to access it. If you have installed TortoiseSVN already you may be thinking: "So why do I have this shortcut in the start menu?"

If you click that shortcut you'll be presented with a dialog box explaining that TortoiseSVN is a shell extension. This means that it will be present in you context menu, usually when you right click inside any folder on windows explorer. It is that interface that you'll be using.
Waning messagem when you click the shortcut in the Start Menu

Available menus to access TortoiseSVN options

Creating a working copy

Subversion is a server centric version control system, which means it needs a dedicated server^[1] to keep track of changes, your revisions and to manage all operations. When you use Subversion you always use a copy to work on, that copy represents the state of a given revision that exists in the server.
To get a copy you will need to checkout a revision.

Create a folder where your work will take place, navigate to it and access the context menu by right clicking inside the folder. In the menu you'll see the option to checkout the project.

Checkout dialog window

In the dialog window above you'll need to fill in the repository URL and choose a given revision. If you just want the last revision, that is, the most up to date code, just leave the HEAD revision option selected.
You can choose to get an old revision from the repository, as the repository I'm using for this tutorial is empty there are no other revisions other then HEAD

Press OK to start downloading the files, after a successful checkout TortoiseSVN will show a summary with the current HEAD revision number and the files downloaded.

Checkout summary

Subversion uses a hidden folder to keep track of changes that occurred in a given folder. Every folder under version control will have it's own .svn sub-folder, that will contain all information a Subversion client needs. If you have chosen the option that makes windows show hidden files you'll see the folder I'm talking about in you recent checked out copy.

Working copy, currently with only the .svn folder

Please don't delete this folder, if you do, TortoiseSVN will no longer know that the working copy refers to a Subversion repository, the link between your copy and the files at the server will be lost.
Also keep in mind that a subversion client can't keep track of changes made using the operating system commands, e.g.: deleted, moved and/or renamed files. If you need to do any of these operations use TortoiseSVN's menu, it has all the options you need and in that way, both your repository and your working copy, will be in good health.

I feel I need to stress this a bit. I've seen some users try to move a file using the normal operating system move option and then complain because the Subversion client got all confused. An SVN client keeps a copy of your files inside the .svn folder, if you move a file without telling the client he will have two contradiction orders, one will tell him that there should be a file for which he has a copy and is keeping revision information, the other telling him that the file is not there. TortoiseSVN will try to decide on what to do, the normal decision is to get the file back from the server. If you have moved the file to another location inside the working copy you'll end up with two copies of the same file, both being tracked by the version control system. But sometime TortoiseSVN will decide that something is very wrong with the local copy and you won't be able to push the changes back to the server, or worse, you'll have to loose some of your work to get things back to normal.

First COMMIT

We are now ready to commit our first changes to the repository. Though you can have any structure you want it is recommended to use the "Subversion way", that is to have 3 folders named, branches, tags and trunk.
Trunk is used for the normal work, it can hold a stable version of your code or the unstable, it is up to you. But it's the place where the main development takes places.
Branches is where you put your experiments, or changes from the normal code orientation. You can use it also for code maintenance after a given release.
Tags are normally used to mark a given revision number with a special meaning. For example, a stable release made public that is not to be changed.
You can have several projects in the same repository or one project per repository, the structure is really up to you.

After creating the folders for the structure we are using, we access the commit option in the context menu.

When you press SVN commit... you'll see a window like the following image, it will allow you to put in the details before commit changes. The interface is very easy to understand, you can input a comment, select what files and folders should be committed, ignore files, etc.

Commit dialog, with spellchecker

Again, after the commit, TortoiseSVN will show you a summary of the changes. This window will also show any error that may occur.

Having a team is best! Updates and conflits

So far we have been working alone, but the benefit of using a version control system shines when you have a team of developers. So we simulate a second programmer by creating a new folder and getting a working copy in that folder, like we've done before, and we add a few more files.

Second working copy

Now we have two different copies, you can have as many as you want, just remember that TortoiseSVN will treat each copy as two completely independent copies.

Our copies contents

After we commit the changes in both local copies, the server will merge them together, and an update will bring them to the working copies. Note that, unless there is a conflict that the server can't resolve, a commit will be successful and you won't be notified if anyone has made other changes, therefor, to know if any change has happen since you last updated your copy, you need to issue an update command, available through the TortoiseSVN's menu.

You may be thinking, what conflicts is the server able to solve and what are the ones he isn't, and what happens if the server can't solve the existing conflicts? Well, the server is smart enough to manage almost every change in the files, but he is limited to text files, binary files, like images, don't cause conflicts as the server doesn't try to marge one over the other. Other conflicts that the server can't solve by himself is the ones that occur when two different programmers change the same line of text in the same file.

Will simulate a conflict by editing the same line in the same file, on the tow different copies

The first programmer changed the empty.txt file and committed the changes, the second programmer has also edited that file and is ready to commit his changes.

When the second programmer tries to commit the his changes an error message is shown in the summary dialog

This message doesn't indicate a conflict yet, what it tells us is that our copy is older than the one in the server, and we can't push changes from old copies, so we need to update the working copy.

After issuing the update command we get our conflict

If we close this window we can see that inside our copy there are a few extra files that were not there before, and that there is a different icon in the empty.txt file

On our working folder the conflict is marked by a little warning icon

Right click the conflicting file and choose "Resolve conflicts..." from the TortoiseSVN's menu. You'll be shown a diff application that allows you to resolve the existing conflicts. The interface is again simple to use and understand.

Diff application

Options are available if you right click the line or text block that is making the conflict. We will choose the option that allows us to replace one line for the other and then we'll mark the conflict as resolved using the toolbar bottom.

Replacing one line for the other

Marking as resolved

You can see that on the left pane refers to the file on the server, the right pane to the local file, and the bottom section to the result of our choices.

The context menu in this diff application, though simple and with only 4 options, allows us to solve every type of conflict, and if you make mistakes, there are options on the toolbar to ignore the changes, navigate between the conflicting lines, and so on.

After you mark the current conflicting file as resolved, close the application. You'll notice that the former strange files are gone and that the @@empty.txt@ file now displays the normal modified icon. Just commit the changes and continue working as normally.

Conclusion

This is a very simple tutorial focused on stating to use an SVN client without much thought on how the Subversion system works internally. This is far being a complete tutorial and is not a substitute for the Subversion documentation and TortoiseSVN help. Nevertheless it will help you start working with a version control system.

Here is an image of all the available options, note that these options are available only on folders that contain working copies. You can explore them on your own but the TortoiseSVN help is a very good place to learn about them.

Notes

[1] You can install the Subversion server on you machine and have a "local" version control system. You'll have all the options as any external server and TortoiseSVN will work fine with a local server. Nevertheless the configuration of a Subversion server, either local or on a remote server, is outside the scope of this tutorial.