Visual SourceSafe - Help Is Here



Table of Contents

The current documentation for Visual SourceSafe is terribly meager, especially as it pertains to playing well with Visual InterDev. After much struggling, trial and error, and reading of particularly vague and useless documents I have written one of my own.


VSS Remoting

Visual SourceSafe 2005 supports remoting. For more about this and a heck of a lot more, I recommend you read Alexandru's book on this product! Besides just documenting VSS, there is a fantastic overview of source control in general.

Try to find any mention of remoting to a VSS 6 database over the internet and you'll come up with scraps. If you search on the net you'll come up with many references to the SourceOffsite (SOS) products by SourceGear. Visual SourceSafe's connectivity is very rudimentary (as far as I can tell) and works through standard file system API's (presumably those in the Win32 API). As such it can handle any path that Windows understands, but is also limited in the same regard. In order for you to connect to a VSS database remotely you must be able to see the SRCSAFE.INI file through the standard file system (e.g. through explorer).

I'm currently trying out SourceOffsite to see how well it works, but please note that the Windows 95/98 server program destroys the network-ability of a Windows ME machine after a client from Windows XP attempts to get the database structure. I don't know if the problems are limited to this situation or broader, but it is pretty irritating to say the least.

As for wishful thinking, it'd be cool if there was a program that sat on both a server and clients which emulated a normal windows drive. That way programs such as VSS could enjoy network connectivity transparently. Not to mention how cool it would be to have a secure drive that has been mapped to your home computer from work. Maybe there is such a thing (please note I mentioned the word secure intentionally!) and if there is, let me know!


Interfacing with InterDev

You would've thought they'd tackle this with some simpler approach or at least documented how this works. I've searched the internet for scraps on "InterDev with Visual SourceSafe" and come up with less than satisfying results. I can't guarantee that after you have InterDev and SourceSafe "working" that you won't have problems, but that's your own fault for using InterHell ... er, InterDev in the first place.

InterDev accesses Visual SourceSafe "automatically" through FrontPage Server Extensions which interacts with IIS and then VSS using it's COM API. Supposedly this whole setup is for "robustness", a word I'm sure they felt clever for using as most do. This means that to actually be able to use Microsoft InterDev with source control for any Web Project, you must have Internet Information Services (IIS) installed, FrontPage Server Extensions must be installed, and FrontPage Server Extensions must be configured correctly.

This section assumes you'll be working on a development machine that is different from the one where the actual Visual SourceSafe database is located; and that you want to use InterDev to edit and test files locally before checking them in to that remote server. You may take creative freedoms with my instructions to better suite your needs, but I won't guarantee they'll work. Heck, I can't even guarantee these will work for you if you have the correct situation.

I must also put in a note here on using multiple Visual SourceSafe databases. If you want to use multiple (more than uno) Visual SourceSafe databases with InterDev web projects on a single machine then you're fully screwed. If you have one SourceSafe database for web projects and one or more that you want to access without using InterDev web projects, you should be okay. In this latter case you'll just have to use the normal Visual SourceSafe client program to switch between and utilize the other databases. IIS, FP Server Extensions, and InterDev are too lame to use anything but a single Visual SourceSafe database.

Step 1. Configure Visual SourceSafe

Before anything else you'll need to have your local machine's Visual SourceSafe configured so that it points to the correct Visual SourceSafe database. The typical installation for Visual SourceSafe installs both the server and client components and that's what I'm basing this step on. If you installed Visual SourceSafe from the files on a VSS server (NETSETUP.EXE or something like that), you may have less steps to complete (it may have already done this stuff for you, for all I know).

The first thing you have to do is strip your client's server identity. The API for Visual SourceSafe will not attempt to connect to a remote server by default unless it is configured to do so. Luckily the people who designed this program did not make any configuration utility so you get to do it by hand (yay!) by editing the SRCSAFE.INI file in your Visual SourceSafe directory.

srcsafe.ini

Open this file up and change the Data_Path, Temp_Path, Users_Path, and Users_Txt to point to the correct places on your remote server using UNC paths. For example:

Data_Path = \\server\vssdatabase\data
Temp_Path = \\server\vssdatabase\temp
Users_Path = \\server\vssdatabase\users
Users_Txt = \\server\vssdatabase\users.txt

Technical Note: From reading the knowledge base docs (see References) there is at least one other way to configure VSS to connect to a remote server. What you do is point the "SSCServerPath" value in the registry (under "HKEY_LOCAL_MACHINE > SOFTWARE > Microsoft > SourceSafe") to the location of the "SSSCC.DLL" file on the server (using a UNC path). The API then realizes it's a remote server and accesses the "srcsafe.ini" in the parent directory of that path. Note that the "API Current Database" and "Current Database" values aren't consulted for this matter ... I've tried. I also wasn't able to test and verify this method because it requires direct access to the server on which the VSS database lives (and I didn't have that when writing this doc).

Step 2. Create Your Local Root

Copy the files in the Visual SourceSafe database to your local machine somewhere. You can do this through whatever file management software (Explorer) you want or use Visual SourceSafe: create a root folder somewhere, open Visual SourceSafe, connect to the server's database (should be able to by default), right click on the main project node in the database, select "Set Working Folder...", choose the folder you created, and lastly right-click and select "Get Latest Version" (make sure "recursive" and "build tree" options are checked).

Step 2. Configure Internet Information Services (IIS)

Open up the properties for the Default Web Site. You can do this by right-clicking on it and selecting "Properties" from the context menu.

Default Web Site Properties

There are three things you now need to set here. First you need to set the home directory to the folder you put all of your web project files in (from the server's Visual SourceSafe database or shadow directory).

IIS Local Path

The second thing you need to do is select the "Server Extensions" tab. Here you will find a drop down for "Source control" which you should select "Use External..." from. If you do not see "Use External..." on the list then you haven't properly configured or installed Visual SourceSafe. After selecting this you will be prompted for a VSS path to specify the root project node.

The last thing you need to do is enable Anonymous Access, Basic Authentication, and Integrated Windows authentication. These are check boxes that can be found by selecting the "Directory Security" tab and then clicking the "Edit..." button.

Step 3. Create a Web Project in InterDev

Open InterDev and create a new web project. Name it whatever you want. When prompted for the location of the web project, use your computer's name (since IIS should be running on it). Also select "Master Mode" and connect to the existing project "Root Web". After clicking "Finish" go grab something to drink because it sometimes takes a while to figure out which shoe is on which foot.

Step 4. Clean Up Mess

After the project is all opened up you are practically done. The first time you do all of these steps it will check out all the files under your name and yet won't let you edit them. If this happens open your VSS client and go to the project's root node and do an "Undo Checkout" with the "Recursive" option checked. After that you need to do a "Recalulate Links" in InterDev by right clicking the project node and selecting that option. That also takes a while so go grab yourself another cup of joe.

Lastly, I must warn you that InterDev caches a lot of things so what you're working with might not be exactly what's in the Visual SourceSafe database. Things you can do to update/refresh InterDev are running "Recalculate Links" and "Get Latest Version" from the context menu that pops up in InterDev when you right-click a web project.


Appendix I. IIS on Windows 2000

Installing

Internet Information Services (IIS) is a Windows Component and thus is not installed via a normal setup program, but through using the "Add/Remove Windows Components":

Control Panel Add/Remove Programs

When installing for using with Visual SourceSafe and Visual InterDev, you must make sure that FrontPage Server Extensions is installed as well:

Diagram: Installing IIS

After installing IIS you can download updates for it from Windows Update.

Configuring IIS

IIS is configured using the Computer Management Console which you can access from the "Computer Management" short-cut in the "Administrative Tools" folder, or by right-clicking "My Computer" and selecting "Manage":

My Computer
Right Click Manage

Control Panel

Administrative Tools

Computer Management

There is also usually a short-cut in the "Administrative Tools" folder which opens up the console with only Internet Information Services and not all the other stuff:

Control Panel

Administrative Tools

Internet Services Manager


If you don't have this short-cut and wish to create one, just use the following data:

IIS Shortcut


Subversion for VSS Users


Introduction

Visual SourceSafe Logo

There isn't a lot of Subversion Tutorials out there, especially for those trying to break away from VSS (Microsoft's Visual SourceSafe). Having worked with VSS for years, it was initially difficult to be sufficiently motivated to move on, even though I was deeply acquainted with all of its failings. It's even more of a challenge when a large team or company has time, training, and space invested. The consensus for those already using Subversion, it seems, is that you want it enough to deal with some pain.

Subversion Logo

Personally I needed to not only become intimate with Subversion, but convey my knowledge to many others and migrate a lot of projects from Visual Source Safe. Existing documentation isn't lacking in detail, it just isn't comfortable stuff. I'm hoping this tutorial will make a scary transition a bit softer. I'm assuming you're a VSS hold-out ready to move on, but unsure how to do it. I will try my best to relate your prior VSS knowledge to new Subversion concepts.

Part 1: VSS compared to SVN

Pre-requisite(s): Experience using Microsoft Visual SourceSafe.

Goal(s): Show Subversion equivalents of VSS terms and syntax.

This section isn't you're typical "VSS versus Subversion" where I debate the pro's and con's of each. Instead, I just want to cover some high-level differences, mostly just in the terms used.

First, VSS is to Microsoft Visual SourceSafe what SVN is to Subversion: short-hand. I tend to write out the term Subversion and abbreviate VSS in this tutorial, because it's intended for beginners.

The phrase "source control" is traded for "version control". These are interchangeable.

VSS has the concept of a database whilst Subversion uses the term repository, sometimes shortened to just "repo". These things are basically equivalent: file stores which track changes.

VSS databases are referred to by file paths (\\server\share\srcsafe.ini, c:\vss\db\srcsafe.ini, etc.) whereas Subversion uses a URL syntax (file:///svn/repo/, http://server/repo/, etc.) to identify repositories.

VSS vs Subversion: File Store Terms

Part 2: Work-flow Overview

Pre-requisite(s): VSS usage experience.

Goal(s): Demystify the basic Subversion work-flow in comparison to VSS.

In the VSS world, and other Microsoft products continuing to this day1, you checkout one or more files and then begin working on them. The idea of checking out is that you lock the file, others see that you have it locked, and only you can work on it2. In order to even checkout a file you set a working folder, where the files will be located locally on your computer. Those files within your working folder are marked read-only unless you've checked them out, so you know which ones you can edit. Finally when you're finished making your changes, you check them in.

Subversion, on the other hand, uses an entirely different approach. First you'll do a checkout to create a working copy; VSS semi-equivalent: set a Working Folder and then Get Latest Version. Next you edit the files locally and when you're ready to publish the changes, you commit them. You can continue to make changes and commit each time when you're ready to push them to the repository. To get the latest changes, such as what other people have committed, you must do an update.

You still have to checkout before you can make changes and publish them; the fundamental difference here is that you don't checkout/lock files in order to edit them, the terminology of the word checkout itself is even completely changed. Some other things this brings up is: you can't see what people are working on (only what they've previously committed), you can have multiple working copies as opposed to just one working folder in VSS, you can't do an update until you have checked out a working copy, and you generally won't know if there's a problem until you commit.

Conflicts are the most common issue preventing you from committing, e.g. when someone else has edited the same file and committed it before you. Thus when you try to commit your changes to the same file, Subversion gives you an error, at which point you'll perform an update to merge the latest changes with your own. Finally you indicate to Subversion you've resolved the conflicts and then it will let you commit the finished result3.

Renaming, adding, deleting, and moving files or folders in VSS is done from the client and effects the database immediately. Subversion, again, differs in that you make these kinds of changes to your working copy and then commit them. You can batch up multiple structure changes and commit them all at the same time.

Commits are the big thing in Subversion. Whenever you're committing, you're making a change to the repository. If you didn't commit, it didn't happen (to the server), and no one else will see it. Before you hit commit, you can revert any one or all of those local changes. Reverting is basically equivalent to Undo Checkout in VSS.

Part 3: Software

Pre-requisite(s): Get TortoiseSVN from tortoisesvn.tigris.org.

Goal(s): Introduce TortoiseSVN and create a local repository with it.

TortoiseSVN Logo

TortoiseSVN is a nice, graphical application (with an active development community) for interacting with Subversion repositories; the basic Subversion package is made up only of server modules and command-line tools. This tutorial is geared exclusively towards the use of TortoiseSVN rather than the command-line tools. Either one works fine, though, and later you might even prefer something other than these two. I like to think of TortoiseSVN as my new VSS replacement, because unless you're working with the server-side of Subversion, that's all you'll ever see.

TortoiseSVN Integrates w/ Windows Explorer

At the same time you may also find TortoiseSVN to be invisible or rather implicit. It integrates itself with Windows Explorer so you will launch various actions/commands by right-clicking files and folders4. SourceSafe, on the other hand, is a stand-alone application which you launch to perform all your actions. In case you were wondering, there are ways to integrate Subversion with Visual Studio, but those won't be covered in this tutorial. I find that new users have trouble enough understanding Subversion without Visual Studio trying to do things for them, and thus adding more confusion.

Now let's step through creating a repository on your workstation using TortoiseSVN. You'll be able to use this repository to practice the things I'll be talking about in later sections. If you already a repository, or at least you think so because someone gave you a URL and said "Start putting your code into Subversion", you can skip this.

First thing you'll want to do is pick a folder where your repository will be located5. If you're unsure, create a folder on C:\ called MyRepo. Right-click the folder you've created and select TortoiseSVN > Create repository here.

TortoiseSVN > Create repository here

The only thing you'll be asked is what type of repository, and there are only two options. Choose Native filesystem (FSFS). This is just how the repository will be represented on disk and FSFS is the best choice in most cases.

Create Repository Types

Hit OK and voila, you've just created a repository!

Repositories are identified with URL's, as mentioned previously, and thus you won't refer to your new one as C:\MyRepo\ but rather file:///c:/myrepo/. Being that the URL points to a specific file path, realize that you won't be able to use this over the network. Setting up a network-accessible repository, via HTTP[S] for example, is an entirely different tutorial! This will at least give you something to play with to get the hang of using Subversion.

It is a good idea to keep the drive and repository name lower-case in your URL, because you'll have to get in that habit when working with http:// URL's later on.

Part 4: Importing a Project

Pre-requisite(s): Your Subversion repository URL (my examples based on the file:///c:/myrepo/ created in the previous section) and a project to import (download ExampleProject if you don't want to bother).

Goal(s): Steps to get a project, not already under source control, into a Subversion repository.

The TortoiseSVN > Import command is one method of putting a new project into a repository, there are others I will get to in later sections. Importing a project copies files and folders from your disk into the Subversion repository of your choice, nothing more. It is intended for projects which you have started without source control and now want to bring them in. At this point, I'm guessing you've never added anything to your repository, so this is exactly what we want to do.

VSS has no equivalent command, generally what you'd do is painstakingly create all the individual nodes of the project and then add files to them. There are ways to migrate a VSS database to a Subversion repository, thereby retaining the history. That's the theory anyway. I recommend against it: the software to do these things is generally poorly supported; your results will vary. If you've moved, renamed, and/or deleted a lot of things in VSS, you've irreparably messed up the history anyway.

Before importing a project you got from VSS into Subversion, make sure to mark all the files as write-able (e.g., not read-only) and remove every vssver.scc file you can find; these are marked as hidden by default. In any case, setup the hierarchy of files and folders as you would like them to appear in the repository. You must have a folder that represents the root folder of the repository. This is generally where people run into trouble, they'll import a particular folder and its contents go into the repository off the root.

Setup project on disk as you want it to be imported into Subversion
1. Setup your project file structure the way you want it to be in Subversion.

To perform the Subversion import of the file structure you've created, right-click the folder representing your root and select TortoiseSVN > Import. Remember that you need to select the folder above your project folder, otherwise the import will pull in the contents of your project but not its folder!


2. Right-click the folder containing your project folder and then select import.


Enter the URL of the destination repository and optionally some comments. When importing a project that was in VSS, I suggest something along the lines of:

Imported from VSS
Database: \\server\share\srcsafe.ini)
Path: $/Path/To/Project/

Click the OK button to begin the import, but don't walk away just yet. You may be prompted to enter your username and password. Also, if this is the first time you've connected to a repository with a HTTPS URL, you will also be prompted to accept its certificate. Once rolling, the import may take a while, depending on the total size of data and where the repository is located. When it completes, you'll have to click another OK to close the import log window.

Finally, let's use the TortoiseSVN > Repo-browser to view what you've imported, to see how it looks in the repository. The initial dialog is simply: enter the repository URL. If the URL is not pre-populated, click the drop-down arrow and it should be in the Most-Recent URL's list. Click OK and you'll see the Repo-browser. As mentioned in the previous section, the Repo-browser is somewhat like VSS and a comfortable sight for those nervous in new territory. As it is a standard tree-view, there isn't much I should have to tell you about how to use it. You can right-click files/folders to bring up various actions that will be performed directly against the repository.

Back to those files on your disk which you ran the import on. I recommend backing them up if you don't yet trust Subversion and what you've put into it, or deleting them if you do. You can't edit the files in their current location and push the changes to the repository, that's what you'll need a working copy for.

Part 5: Working Copy

Pre-requisite(s): Subversion repository containing some files/folders.

Goal(s): Get a local copy of a project from a Subversion repository.

In VSS you checkout files in order to work on them, and then you check them in when you're finished. Thus you don't actually edit the files directly in the database, but rather you make the changes to files on your computer and then upload those modified versions into the database. The location of these local files is determined by the Working Folder setting for the VSS project you're working on. The VSS client stores the information about your working folders on the server, basically in the VSS database. So every time you launch VSS with a particular user, it knows where you're working from.

Subversion is the same in that you edit local files before committing those changes to the repository. Instead of a single working folder for a project, however, you create a working copy using the checkout command. TortoiseSVN identifies working copies through hidden folders named .svn6 which is sort of like SourceSafe's vssver.scc files. Note that TortoiseSVN notes this information locally and not on the server where the repository is. This is generally fine, because there's no stand-alone client to run like VSS and therefore no reason to keep the information on the server.

Alright, now let's get a working copy of a project to play with. Right-click a folder where you'd like to create a working copy and then select SVN Checkout. Enter the URL of the repository and add the name of the project at the end. This will ensure that we get a working copy of just that folder and its contents, not the entire repository. Just like in VSS you will probably only work on certain projects at a time and not want to grab a copy of the entire database. Remember, a Subversion checkout does not lock the files so other developers (if this is a shared repository) may checkout files and edit them locally as well; neither of you would know through TortoiseSVN. This is different from VSS where you can kind of tell when someone is working on something, because you can see if they have it checked out or not.

What you put in the Checkout directory input box will become your working copy. Think of it saying "Working Folder" instead of "Checkout directory". I generally keep this folder named the same as the project so as not to get confusing, so in this case I'm using C:\Work\ExampleProject.

After you click OK, TortoiseSVN will prompt you if the folder doesn't yet exist. Otherwise it will download all the latest files from the repository and plop them down, along with a .svn folder per working copy folder.

Now it's time to explore your working copy. Open up the folder or drive which contains the final project folder you created. It should have a green checkmark overlay. This means that TortoiseSVN recognizes it as a working copy of something in a Subversion repository, and it hasn't been altered.

Opening up the project folder you'll see the .svn folder (if you can see hidden files/folders) and all the other files and folders will have green checkmarks on them as well. My example project is a single text file, so there isn't much to see here.

Finally, right-click on a blank spot inside the folder to bring up the context menu. You'll see SVN Update (VSS: Get Latest Version) and SVN Commit (VSS Checkin) instead of SVN Checkout, and a TortoiseSVN> menu will be available as well. Note, then, that you can't checkout multiple projects from Subversion to the same directory whereas in VSS you can have them share the same working folder.

Part 6: Edit, Diff, and Commit

Pre-requisite(s): Working copy of a project in Subversion.

Hopefully you're still here, now that we're finally getting to what you'll usually be doing with Subversion; the standard work-flow if you will. Unfortunately it may be disappointing how simple this part is.

Open up a file you want to edit in your working copy using your favored editor. Make some change, any change, and then open the file's parent folder.

Notice the green checkmark is gone and instead there is a red exclamation mark. It is meant to grab your attention and doesn't signify there is a problem. What it does mean is that the file is different than the one you last got from the repository. Move up a folder and you'll see that the containing folder even has this icon. That display will show up at the top-most folder in your working copy. In my example, that means this will be shown on the ExampleProject folder, but not on its parent: C:\Work.

Assuming this is a text-based file you can see line-by-line differences by right-clicking it and selecting TortoiseSVN > Diff. For those of us quite used to SourceSafe's visual differences, this will be a treat. Not only can you see line-by-line, but if you roll the mouse over a changed line, it will show you exactly which characters at the bottom. Also, character (as opposed to whole line) differences use a slightly different color. This is helpful if you indent or de-indent a bunch of stuff, because it won't look like a huge block of changed code.

At this point in VSS you'd checkin to publish your changes to the database, assuming you were finished editing locally. With Subversion what you'll do is commit all your changes to the repository. Do this by right-clicking that file you edited and selecting SVN Commit.

For the most part, the commit dialog (Enter Log Message) dialog is fairly self-explanatory. It looks a lot like Visual SourceSafe's checkin dialog. You can enter a message, like a VSS checkin comment, and there are some wacky checkboxes that I'll get to in a bit. Also notice it has a list of files that are being committed. If you had edited multiple files within the working copy, you can right-click the folder and select commit to publish all these changes at once.

When you've clicked OK TortoiseSVN will contact the repository, build up a transaction for the commit, and then send off all the changes. Depending on the amount of files you're committing changes for, it may take a while and the progress dialog isn't very helpful. Luckily it doesn't copy whole files, but rather only differences between them. This is helpful when working with remote repositories on, for example, http:// URL's.

Because you never did a VSS-style checkout, there was no lock to unlock, and thus you can continue to edit and commit, again and again. You may need to occassionally get the latest versions of files from the repository, however. Get the latest files when other developers have made changes, or maybe you've made changes to another working copy elsewhere, by right-clicking the project folder and selecting SVN Update. As long as you haven't changed the files being updated, this will pull down all the changes without needing input.

It's important to update periodically so your working base is up to date. You may have noticed in the differencing GUI that it shows "working base" on the left and "working copy" on the right. Of course the working copy is the files you've edited, but what is the working base? VSS is always communicating with the server, so doing a diff goes against the latest files in the database. Subversion doesn't require constant communication with a repository, instead the last files you got from it are stored in the hidden folder (.svn in most cases 6) which is known as your working base. When you do a diff, it goes against these files which means, yes, they might not be the latest. Again, that's why it's so important to keep your working copy (and base) up to date.

To see the changes that have been made to projects, use the TortoiseSVN > Repo-browser as touched on in an earlier section. Again, the Repo-browser is a lot like the VSS application you're used to except there's no menu bar or toolbar. Remember you can right-click items here and see their history with Show log. Every time someone commits a change to the repository, its revision number is incremented. In VSS each individual file has a version number that does this, but in Subversion that number is applied to the entire repository.

Undo your local changes, like VSS Undo Checkout, using TortoiseSVN > Revert. You can either select specific files before right-clicking, or just right-click the project folder. In either case you'll be shown a dialog which shows the exact list of files to be reverted.

Before we move on, the biggest question in a VSS user's mind is: "How does Subversion prevent stomping if checking out doesn't lock files?" In short: Subversion simply won't let you commit if someone else has commited before you. You are forced to merge conflicts in the changes, sign off on the merge, and then you can commit. It is not possible to accidentally stomp changes, you can do it, but you have to be mighty persistent. Conflicts and merging are complicated enough that I won't go into them in this section, and singular administrator/developers won't care besides.

Part 7: Adding Files/Folders

Pre-requisite(s): Working copy of a project in Subversion.

Goal(s): Add new files to a working copy project as well as understand working base and the difference between unversioned and versioned.

Remember doing an import and afterwards you just had to trash the files since they weren't working copies? Well, there's an easier way to add files, even whole folder hierarchies, to a repository. The trick isn't really a trick, you just need a working copy that you can add to with TortoiseSVN > Add and afterwards those folders/files become working copies that you can edit and commit!

Let's dive right in by adding a folder containing a file. So first create a folder as you normally would and then put a file in it; remember to do this inside the working copy for your project.

Now that you have those two things, right-click the folder you created and select TortoiseSVN > Add. A dialog will come up that confirms your additions, it looks a lot like the commit dialog but it isn't. In fact, after you click OK, and even after you watch it "add" the files, nothing gets added to the repository. Instead, what this does is tell TortoiseSVN that when you commit the project folder, you'll also want to add these things. Important: it doesn't add them right away!

Ah, so what now? You'll see these new items have plus sign overlays rather than an red exclamation or green checkmark. This is another clue to you that these changes are still just local and your intentions have not been published. As you did with editing files, right-click inside the project folder, or the to-be-added items, and select SVN Commit. Note that now the commit dialog mentions these things will be added, rather than modified. Clicking OK will start the commit and, if it succeeds, then that stuff is finally added to the repository.7

A file or folder that is in your working copy, but is not in the Subversion repository, is considered unversioned. This really goes for any file/folder that is not having its changes tracked, but it becomes especially important to understand in the context of a working copy. If you simply put a new file into your working copy, it is unversioned. Once you've added it to the repository using the steps above, it becomes versioned.

You may have noticed the Show unversioned files option in the commit dialog, which may also be checked by default. This causes TortoiseSVN to list out files which are in the repository, even if you aren't adding them. This is another way to add things to the repository. What you do is check the box next to these unversioned files to make them part of the commit. When you click OK, TortoiseSVN will then add them.

What happens if you try to add a file that already exists in the repository? TortoiseSVN will return an error. Remember that TortoiseSVN also determines versioned versus unversioned based on your working base, not actually what may be in the repository. It's possible someone will add files that you already have in your working copy that are unversioned. When you do an SVN Update, TortoiseSVN will alert you and not overwrite them. One way to solve this (assuming your copy is basically the same content with changes) is to copy the unversioned files to another folder, do the update, and then copy them back over the versioned files. If you don't know what this new, versioned file is then you might have some developer contention and TortoiseSVN can't help you solve that.

Part 8: Deleting Files/Folders

Pre-requisite(s): Working copy of a project in Subversion.

Goal(s): Delete files from a working copy as well as the repository.

Often for VSS you will not have the privilege of fully destroying files. It's an extra permission that must be granted by the administrator and a good one will be loath to do it. The reason being of course, destroying a file in VSS will cause it to be irrevocably lost to the database. You can only then recover it using separate backups. This poses an additional problem with trying to re-get old versions of entire projects, because files that were required back then are no longer available. Whoops!

In Subversion you either have read-only, read/write, or no access to a repository; you can't destroy history without damaging the repository itself, e.g. you have to do it outside the software. There is no permanent destroy and deleted files are always recoverable by getting an earlier version. Recall in an earlier section I mentioned that the entire repository is given a new version when any commit is made, this is called a revision. When you get an earlier revision of a particular folder, it gets its entire structure as it existed back then, even files that have since been moved or deleted.

Anyhoo, here's something fun to try or something irritating depending on if you've had this happen yet already. Find a versioned file, one with a green checkmark and whatnot, then delete it by pressing DEL or dragging it to the Recycle Bin. Now do a SVN Update. It comes back! TortoiseSVN sees that you don't have a file which is in the repository (and in this case, still in the working base) and thus re-creates it.

In order to delete a file from the repository you need to use TortoiseSVN > Delete. The file will usually disappear, and a folder will do the same if you delete it. However, if it happens to come back before you commit, for whatever reason, it will have a red 'X' overlay. This signifies, like the plus sign for add, that when you commit the files will be deleted.

Launching SVN Commit when files are marked for deletion will list them out along with that action. As with anything else, and I can't say this often enough, you won't actually delete the files from the repository until the commit has completed. If someone else has already deleted the files from the repository, you will be rebuffed and have to do SVN Update.

Part 9: Move and Rename

Pre-requisite(s): Working copy of a project in Subversion.

Goal(s): Move and Rename.

Both of these, although different menu options, do practically the same thing. You see Subversion has no server-side method to indicate a move or rename. What TortoiseSVN actually does at the repository level is delete the previous file/folder and add it some place else. This isn't as taxing as it sounds.

First we'll do a rename, because it's simplest. Add a file with an improper name to your working copy so we can try this. Right-click it and select TortoiseSVN > Rename. The dialog you'll get is about as simple as you can get, just type in the name name.

Now do SVN Commit and you'll see it's going to delete the file of the old name and add the one with the new name. When you click OK then you won't actually be uploading the file data (unless you've changed the renamed file of course); TortoiseSVN and Subversion are smart enough to know that the file data is the same.8

Moving files and folders is only slightly more complicated. First, make sure where you're moving them to is already versioned. That is, if the folder you're moving them to isn't already in the repository, then add it.9 Then to do the move, right-drag (click and hold the right mouse button) the item(s) to the new folder. When you let the mouse button up, select Move versioned files here from the context menu.

Just like a rename, when you do your SVN Commit you will see the files in their previous location marked as deleted at the same time as being added to the new location.

To undo a rename or move before committing, select TortoiseSVN > Revert from the folder above both locations. Make sure to check the boxes next to both the deletes and the adds before clicking OK.

End Notes

1 Current editions of both Share Point and Team Foundation Server require you to checkout to modify files.

2 VSS supports "Multiple checkouts", but there are enough issues with them that they are rarely used.

3 When the amount of conflicts becomes especially cumbersome, there is the option of using branches for smoother, parallel development.

4 You'll also find TortoiseSVN on the File menu of Explorer windows, but this tutorial deals exclusively with right-click (context) menus.

5 When you install Visual SourceSafe, it will typically set you up a local database. TortoiseSVN doesn't do this.

6 If you want to use Visual Studio 2003 and Web Projects (ASP.NET 1.1), however, working copies will have to store their information in a _svn directory (not .svn).

7 No commit, no change made to repository. It's that simple. All changes from a working copy must be commited. Using the Repo-browser doesn't utilize a working copy and therefore doesn't have a commit, and happens immediately.

8 When you make a small change to a large binary file, the commit doesn't take very long because TortoiseSVN just tells the Subversion repository what the changed bytes are.

9 It's possible to add folders and move things into them at the same time. The old files/folders will simply be deleted and added at their new location along with the new folder.


Contact

Comments or questions? Email me at webmaster@neilstuff.com.