you're reading...

10 minute guide to starting with subversion and tortoisesvn

Luc messaged me earlier yesterday evening and mentioned that he was interested in starting to use some source control on his own code so I thought I’d whip up this post so others could benefit from my set of instructions.

The steps I describe here are suitable for when you are working by yourself and want to have your source versioned. The subversion documentation outlines the steps you need to take to host the repository so others can access it. I may write a post for that too, if there is interest.

The steps in the full text of this post will have you install tortoisesvn — my tool of choice for working with subversion; create a subversion repository, and add a new project to the repository and any existing files you may have. I’ll also describe what you need to backup to ensure you won’t lose any work in the event of a hardware failure.

Step 1: Download and install the latest TortoiseSVN. Once it is installed it will tell you that you need to reboot, unless you’ve installed TortoiseSVN before you don’t have to.

Step 2: Create a directory on your computer that will be used to store all of the important files you’ll check into subversion. This is not where you will be doing work but where all the book-keeping will be taking place. For these steps I’ll use C:\my\svn\repository

Step 3: Right click on said directory, choose TortoiseSVN/Create Repository here. You’ll be asked what kind of repository you want, choose Native File System (FSFS). Make note of where this directory is at, you’ll need it in a few steps. But now leave this directory because you won’t be touching the files here directly anymore.

Step 4: Now we’ll create the directory structure within the virtual filesystem of the repository. I like to organize my repository by project where each project also has a tags, branches, and trunk directory within it so thats what we’ll create here.

Step 4a: Create a directory somewhere; this will be used only temporarily so it doesn’t matter where it resides the name doesn’t matter either.

Step 4b: Create a directory within that one named for your project

Step 4c: Create 3 directories within the one named for your project named: “tags”, “branches”, and “trunk”

Step 4d: If you have existing source for this project place it inside of the “trunk” directory. You should clean it up so that only source files are checked in. bin, obj, and any .user files should be deleted or you’ll just bloat the size of the repository for no good reason.

Step 4e: Go back to the folder containing the directory you created in 4a.

Step 4f: Right click on the directory created in 4a and choose: TortoiseSVN/Import…

Step 5: It will ask for the repository, remember that directory created in step 2? Specify the repository as file:///C:/my/svn/repository/ it is very important that you include three forward slashes after file: and before the drive letter. Click OK.

You should see tortoise begin to process and in the end you will have 4 (or more) directories added to the repository.

We’ve created the repository and added any existing files to it, now its time to get your work area ready to be handled by subversion!

Step 6: Go to where you want your source code for this project to live. In my case all my code lives at D:\projects\<projectname> so I navigate to D:\projects.

Step 7: Right click on an empty place in this folder. Choose SVN Checkout.

Step 8: URL of Repository should still say file:///C:/my/svn/repository/ that you typed when you imported the files. If it doesn’t, type it in here.

Step 9: Click the ellipsis button (…) next to the URL of the repository, this will bring up the repository browser. Expand the folders until you are at <project>/trunk. Select that folder and click OK.

Step 10: Where it says Checkout Directory add the name of your project to what is currently displaying (since I did this in D:\projects\ it currently says D:\projects\ I will modify it to say D:\projects\myproject). Click OK. You will be asked if it is okay to create the directory; tell it yes that it is okay.

And now you’re done. Congrats, you now have a subversion repository on your computer containing all of the files you already had.

IMO, the first thing you should do is set up the filter so that you don’t add files to the repository that shouldn’t be. This goes back to the bin, obj, and .user files you didn’t add to the repository to begin with.

Right click anywhere in Windows Explorer, choose TortoiseSVN/Settings. Set the global ignore pattern to:

bin */bin obj */obj *.suo _ReSharper.* *.resharper *.resharper.user *.user

Now when you use TortoiseSVN files and directories matching the pattern will not be shown.

How do I use TortoiseSVN?

Now that you have the repository set up; its time to make use of it. The bulk of your usage will be to commit changes that fall into 3 categories, files that have been: added, deleted, or changed.

Windows Explorer should now display a green checkmark on the newly created folder for your project. This green checkmark means that the directory and all subdirectories have the latest revision of the files in the repository.

So everyone can follow along at home we’ll add a file, edit it, then delete it from the repository.

Adding a file

Inside of your project directory create a new text file. Call it newfile.txt, go ahead and add some text to this file; it doesn’t matter what. Save the file and close it.

Back in windows explorer you can right click on the file if you only have one file to add or you can right click on the containing directory. Choose TortoiseSVN/Add from the context menu. If you don’t see a Blue + sign on your file hit F5 to refresh the directory. Right now the files are only queued to be added in the next commit to the repository.

Right click on the project directory, choose SVN Commit from the context menu. You will be presented with a dialog that allows you to give a message detailing what changed in this commit at the top, and the ability to select which changes will be committed. Type your message and ensure the files are selected to commit (newfile.txt for example). Click OK. You’ll be presented with a dialog showing the progress as the files are sent to the repository. If all goes well you will be presented with a success message and the new revision number.

Editing a file

Open up the file we just created and make some changes to it. Save the file and close it. Refresh the directory. The file will now be marked with a red exclaimation (!) alerting you that the file no longer matches the latest version in the repository. Let’s fix that.

Right click on the directory and choose SVN Commit. As before when you added the file you can enter a reason for the commit and select the files to commit. Click OK. Same deal as before when you added the file you’ll be presented with a success message if everything went ok.

Refresh the directory containing the files and you’ll see that the blue + has now changed to the green checkmark.

Recovering an older version of a file

Before we get to the deletion of a file; lets talk about how to recover an older version of a file. Now that you’ve added and edited the file newfile.txt we’ll recover the first version. Right click on the file, choose TortoiseSVN/Show Log. You now see a list of all revisions that contain this file. You now have several options available. Right click on one of the log entries, you’ll see several options relating to changing the existing file based on the log entry you clicked.

  • Update item to revision: Use this option when you have an old version of the file and want to move up to the one in the revision you selected
  • Revert to this revision: Use this option when you have a newer version of the file and want to move everything back to as it was in this revision
  • Revert changes from this revision: This one is difficult to explain; but it will mark the file as having a conflict then create 3 additional files that will allow you to manually merge the changes you want to make.

For our purposes select revision 2, the list of actions at the bottom should say that you added the file. Now right click on the revision, and choose “Revert to this revision”. When asked if you are sure, tell it yes. The TortoiseSVN Merge dialog will appear then tell you it has finished. Tell it OK and then OK out of the show log dialog. Refresh the directory and you will see the red ! on the file again telling you that it no longer matches the repository.

As you did before, right click on the directory and choose SVN Commit, provide your log reason and click OK to commit the change. When it is done you’ll notice that the revision doesn’t say 2, this is natural. After all, if you lost all your edits after you revert a file you wouldn’t be able to undo that edit, would you?

Now that you’ve seen how to add, edit, and revert a file we have one more thing to do.

Deleting a file

In explorer delete the newfile.txt file. Right click on the directory and choose SVN Commit. Like before you’ll be presented with the same dialog. This time you will have to manually check the box next to newfile.txt to indicate that it should commit the delete to the repository. Click OK.

Backing up the repository

At the very top of this post I mentioned you would learn how to back up the repository…simple; just zip up the directory you created in step 2 and put the zip file some place safe. If worse comes to worst and you need to restore this backup; just extract the contents of the repository where you want the repository to live then do an SVN Checkout like you did in step 8.

From here the rest is up to you; there is much more that I didn’t cover in this post…perhaps I will be inspired to write a new post in the future.

Update: Stephen Russell on DevelopMentor’s Advanced-DOTNET mailing list posted a link to a blog post that integrates tortoisesvn with Visual Studio 2005.  This is supposed to be a light weight approach to integrating the two.  If you’re looking for full source control integration then there are a couple options available that I know of.

  • VisualSVN is a commercial product that quite a few people on the same list recommended using.  The developers also posted a comment here on an earlier blog-post of mine so they are reaching out to community posts.
  • AnkhSVN is an open source product that Jason made a comment about and I’ve used in the past with some success.  There is also a blog that comments on AnkhSVN as well; but its been dormant for over 6 months now.

About James

I am a Senior Developer/Consultant for InfoPlanIT, LLC. I previously spent over 7 years as a Product Manager for what eventually became ComponentOne, a division of GrapeCity. While there, I helped to create ActiveReports 7, GrapeCity ActiveAnalysis, and Data Dynamics Reports.


8 thoughts on “10 minute guide to starting with subversion and tortoisesvn

  1. Hey, good post! Hope to see more. As you know, I had meant to make some sort of SVN related post(s) to my blog in the past, and I’ve just never got around to it.

    I’d like to throw a couple tid-bits into the mix, though:

    On deleting files – If you need to delete a file from the repository, I find it more convenient to right click on the file and choose TortoiseSVN->Delete. This will not only delete the file from disk, but it also marks the file for deletion from the repository at the next commit — there’s no need to remember to mark it for commit when you have the commit dialog open.

    Also, on deleting files — when you delete a file from the repository, you’re deleting the file from the committal revision and forward. Once a file has been committed to the repository, it will always have it’s history in the repo, it never leaves. This is nice in that it’s fully recoverable (as you detail) if need be. This is not nice in that you need to be diligent about what you commit to the repository. Many times when setting up a new repository, and importing project code I’ve accidentally imported files I had meant to clean out before the import. Unfortunately, those imported files unnecessarily bloat the repository.

    One last thing, if your development environment is VS2005, you might want to check out AnkhSVN for SVN-integration. It allows you to do most of the things TortoiseSVN allows you to do but from within VS2005. With that said, I’d like to point out that I use nearly none of that feature set of AnkhSVN. I use it for it’s ability to automatically flag a file for addition to the repository when I add it to the project. It also handles deletions, and (most) renames.

    I say “most renames” because there’s a ‘feature’ in Ankh that doesn’t handle renaming just-added-but-not-yet-committed files. Renames in SVN are odd. They’re implemented as a delete-old-named-file followed by an add-new-named-file. It appears that Anhk gets confused trying to do an SVN-Delete on a file that hasn’t been commited to the repository yet. To rename a just-added-but-not-yet-committed file you need to Revert the file, rename, and then Add the file again.

    But anyway…geeeze…big enough comment for you? 😉

    Posted by Yoopergeek | July 12, 2007, 10:31 am
  2. I think it’s also important to talk about branching and merging.

    We just had two major feature branches that had been developed separately from the trunk for 2+ months and let me tell you, it’s a special kind of pain that can only be eased by doing occasional (at least weekly) merges from trunk to keep that final merge from the branch into trunk from becoming a gawd-awful mess of conflicts and lost code.

    We have the process of doing a merge (from trunk to branch and branch to trunk) in our wiki. I helped write it, but I still have to refer to it every time I do a merge. It’s a painful process but it sure beats the alternative.

    One thing that really helped is to read the documentation on branching and merging at least 10 times. One of those times, it will click and make sense.


    Posted by NickKoz | July 12, 2007, 11:16 am
  3. 😉 Keep in mind that branching and merging is only really necessary if you have to work with someone else on a project.

    Posted by NickKoz | July 12, 2007, 11:24 am
  4. Stellar document man!! 🙂 I see myself referring to this quite a bit in the near future, as I’ve began using SVN for one of my personal projects. I’m working through the noob whoas and this will be a great reference…


    Posted by Luc | July 13, 2007, 1:04 pm
  5. Great, very helpful! Much better than reading the documentation. 🙂

    Posted by unknown | December 15, 2007, 3:01 am
  6. Just a quick info for backing up your repository.

    The recommended way to backup your repository is actually is to run the following command (minus the quotes):

    ‘svnadmin hotcopy path/to/repository path/to/backup –clean-logs’

    This will create a copy of your repository in a safe manner, in case someone is committing a transaction during the backup/zip process. Then you can zip the ‘path/to/backup’ directory. The –clean-logs attribute simply removes any redundant log files if you’re backing up a BDB repository.

    Good article!

    Posted by Brian | March 3, 2008, 8:50 am
  7. It is very helpful.Great!!!Thank you!

    Posted by Jegnaw | December 25, 2008, 7:08 am
  8. Verymuch useful for the beginners…Thanks alot…

    Posted by Kumar | September 25, 2012, 8:10 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s


%d bloggers like this: