Converting from Other Version Control Systems

One of the critical areas that you need to consider is how you are going to move your data from your current version control system to Team Foundation Server. Obviously, you want to retain as much history and information as you can from your old system, while converting the necessary pieces into the new Team Foundation Version Control terminology, such as changesets. Using the Team Foundation Server Object Model, you could create your own conversion utility. That is one option. If you are using a custom-built version control system right now, that is probably your only option.

However, if you are using one of the major third-party tools now on the market, such as CVS, Subversion, or Visual SourceSafe, then you have another option. Microsoft provides free with Team Foundation Server a conversion tool called VSSConverter, which allows you to convert Visual SourceSafe information into Team Foundation Version Control. And third-party companies, such as ComponentSoftware (.componentsoftware.com) are providing utilities to convert Subversion, CVS, and several other version control systems, including Visual SourceSafe.

In this section, you learn how to convert your Visual SourceSafe project, using the free VSSConverter tool provided with Team Foundation Server. You learn about some of the pros and cons of converting using this tool. Next, you look at converting the same Visual SourceSafe database using the CS-Converter tool provided by ComponentSoftware. This tool converts information in a slightly different way than the VSSConverter tool provided by Microsoft, so it is worth looking at.

While you won't see a specific example of converting Subversion or CVS to Team Foundation Server, the CS-Converter tool by ComponentSoftware will convert these version control systems in a manner similar to the one shown for Visual SourceSafe.

Using VSSConverter to Convert Visual SourceSafe

The VSSConverter tool is provided free with Visual Studio Team System by Microsoft, for use in converting your Visual SourceSafe projects into Team Foundation Version Control. This tool is located at c:\Program Files\Microsoft Visual Studio 8\Common7\IDE\VSSConverter.exe. It is a command-line only tool, which uses XML configuration files to convert a single VSS project or an entire VSS database, depending on how you configure the application to run.

Important

The MSDN documentation (http://msdn2.microsoft.com) contains a wealth of information concerning the VSSConverter tool. While some of the most pertinent information concerning the tool is presented here, check the online documentation for the latest and most complete information.

All the code mentioned here is available for download at wrox.com.

VSSConverter Information

Before you get started with VSSConverter, you need to briefly understand what it will and won't do for you. VSSConverter does its best to convert as much of the historical information in the VSS database over into Team Foundation Server Version Control. However, some features of VSS, such as sharing, are not supported in TFS. As such, any historical information related to the use of these features will be lost.

The history for all the following items will be preserved with VSSConverter:

• Adding a file or a folder

• Deleting or undeleting a file or a folder

• Renaming a file or a folder

• Moving a folder

• Editing a file

• Modifying a label

The following actions are not supported in Team Foundation Server, and all historical information related to these actions will be lost:

• Sharing

• Branching

• Pinning

Sharing is not supported in Team Foundation Server. When a shared file is migrated, the version of the file that was originally shared is copied to its destination folder. After that, any changes that had been made to the shared file are copied to its original destination folder, and to any other copies of the shared file in other folders.

While branching is supported in Team Foundation Server, it is not supported in the manner that VSS used it. In VSS, sharing a file was a prerequisite to branching the file. When migrating a branched file, the original file is copied to its destination folder. At the point of the branch event, any changes made to a branch are copied to their appropriate area in Team Foundation Version Control.

Team Foundation Server Version Control provides no support for pinning. When a pinned file is migrated, two labels are created for the file: PINNED_LATEST and PINNED. The PINNED label applies only to the pinned versions of the pinned files, while the PINNED_LATEST label is applied to all the PINNED labeled files, as well as the latest version of any unpinned files.

There are two other things to be aware of when using VSSConverter. The conversion tool does not modify the source control bindings on the files. The files will still think they are bound to Visual SourceSafe when you try to open them. You can either change the bindings before you open the files, or Visual Studio 2005 prompts you to change them when you try to open them.

Finally, the timestamp associated with a specific action in VSS will not be preserved when converting over to Team Foundation Server Version Control. Instead, the timestamp associated with the action will be set to the date and time of the conversion. The original timestamp will be stored in the comments field though, so the information is not lost.

Before You Begin

Before you can begin converting your project using VSSConverter, there are some things you need to do, and some security issues you need to be aware of.

Prerequisites

First thing you need to do is find a machine to run the conversion on. This machine will need the following software installed on it:

• Visual SourceSafe 2005

• SQL Server Express

• Team Explorer

Next, you need to make sure your VSS database is ready for the conversion. Have all the users check in their files; then, make a backup copy of the database. Finally, run the VSS Analyze tool to find and fix any errors contained in your VSS database. Once you are convinced your database is ready, copy it over to the conversion machine.

Important

The VSS database must be version 6.0 or later. If you are using an earlier version, you must first convert to VSS 2005.

You need to log into the conversion machine with administrative privileges. Also, you will need to know the administrator password for your VSS database.

Finally, you need to go ahead and create a new team project, or a folder in an existing team project, to convert the VSS information into.

Let's get things set up for you to covert the example in this chapter. Go ahead and install all the prerequisites. Using the downloaded code for this chapter, unzip the MyVSS.zip file to c:\MyVSS on your conversion machine. If you like, you can open Visual SourceSafe 2005 and connect to this database, to view the files, as shown in Figure 12-20. This database contains two projects, VSSTest.root and VSSTest ver2. For this example, are just going to convert the VSSTest.root project.

Figure 12-20

Open Team Explorer, and create a new Team Project called MyConvertedVSS. Go ahead and associate with the version control system when the project is created, using $/MyConvertedVSS.

Security Concerns

You should be aware of several security elements when performing this conversion. You need to be logged into the conversion machine with administrative privileges. You also need to have administrative privileges on the Visual SourceSafe database, and know the administrative password for the VSS database.

You need to be a member of the Team Foundation Administrators security group in Team Foundation Server.

Finally, you need to be a member of the sysadmin role for SQL Express. If you were logged in when you installed SQL Express, then you are added to this group by default.

Analyze the Projects

Once you have the conversion machine configured, you are ready to analyze the projects you want to convert. This analysis will look at the VSS projects, and notify you of any potential errors or loss of data that may occur with the conversion. To run this analysis, you need to create a XML configuration file that contains the settings for the VSSConverter tool. The configuration file contains the following information:

 <?xml version="1.0" encoding="utf-8"?> <SourceControlConverter> <ConverterSpecificSetting> <Source name="VSS"> <VSSDatabase name=""></VSSDatabase> </Source> <ProjectMap> <Project Source=""></Project> </ProjectMap> </ConverterSpecificSetting> <Settings> </Settings> </SourceControlConverter> 

The VSSDatabase tag defines the location of the Visual SourceSafe database to convert. The Project tag defines the specific project in the database you want to convert.

1. To continue with this example, create a new directory off the C: drive of the conversion machine, called Convert. Add a new file to that director called settings.xml. Add the following code to the settings.xml file:

    <?xml version="1.0" encoding="utf-8"?> <SourceControlConverter> <ConverterSpecificSetting> <Source name="VSS"> <VSSDatabase name="c:\MyVSS"></VSSDatabase> </Source> <ProjectMap> <Project Source="$/VSSTest.root"></Project> </ProjectMap> </ConverterSpecificSetting> <Settings> </Settings> </SourceControlConverter> 

   Notice in the VSSDatabase tag now contains the name of the VSS database, C:\MyVss. You are going to convert the VSSTest.root project, so that has been added in the Project tag.

   Important

   To migrate the entire VSS database, use the tag <Project Source="$/"></Project>. It is recommended that you try several smaller conversions before attempting to do the entire database at once.

2. Once you have created the settings.xml file, it is time to run the analysis. Go to Start⇨All Programs⇨Microsoft Visual Studio 2005⇨Visual Studio Tools⇨Visual Studio 2005 Command Prompt, and run the command prompt. Once the prompt opens, type CD c:\Convert, to switch to the directory where the settings.xml file is located. Now run the following command:

    vssconverter analyze settings.xml 

3. You will be asked for the VSS administrator password. For this example, it is blank, so simply press the Enter key. The converter application analyzes the VSSTest.root project in the MyVSS database, makes some modifications to the settings.xml file, and outputs the results of the analysis.

Reviewing Analysis Results

After the VSSConverter has run its analysis, it outputs an analysis report. This report is located in the same directory as you ran the conversion analysis from, and is called VSSAnalysisReport.xml. Figure 12-21 shows the report for our example:

Figure 12-21

This report shows you the number of files and folders that were analyzed, and will list any potential warnings or errors that may occur during the actual conversion. It will give you a good indication of how your conversion process will go, and what things you should watch out for, or check for after the conversion is complete.

Now that you have reviewed the analysis results, you are ready to proceed with the conversion. Before you begin though, you need to make some more changes to the settings.xml file. As well, the analysis run has added another configuration file to your directory, the UserMap.xml file, which also needs your attention.

Customizing Files for Conversion

When the analysis of the database is run, a UserMap.xml file is created. This file can be used to map VSS users to Team Foundation Server users. For example, you may have a user John in VSS, but on Team Foundation Server his name is JohnSmith. This file allows you to map the name John in VSS to JohnSmith in TFS. So, when the VSS data is converted, any files associated with the name John would then be associated with the name JohnSmith in TFS.

Important

You do not have to do this. If you choose not to associate certain names, then the VSS names will be inserted into the TFS database.

The following is an example of what the UserMap.xml file would look like:

 <?xml version="1.0" encoding="utf-8"?> <UserMappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <UserMap From="John" To="JohnSmith" /> </UserMappings> 

For our example, the UserMap.xml file looks like this:

 <?xml version="1.0" encoding="utf-8"?> <UserMappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <UserMap From="DEV1" To="" /> <UserMap From="DEV2" To="" /> <UserMap From="ADMIN" To="" /> </UserMappings> 

Feel free to add users to the TO attribute, or leave them blank if you wish.

You need to make some changes to the settings.xml file before the actual conversion can be run. If you are going to be using a UserMap.xml file, you need to add the following tag in the <Source> tag, just under the <VSSDatabase> tag:

 <UserMap name="[PathToUserMap.xmlFile]"></UserMap> 

This tag tells the VSSConverter application that you want to use a user-mapping file and where the UserMap file is located.

For each of the <Project> tags, you need to add a Destination attribute. This attribute tells the VSSConverter application where in the Team Foundation Version Control system to covert the VSS project:

 <Project Source="$/VssProject1" Destination="$/TeamProject1"></Project> 

Finally, you need to add a new set of tags after the <ConverterSpecificSetting> tag. This tag is called <Settings> and is used to define which Team Foundation Server you want to convert to:

 <Settings> <TeamFoundationServer name="[ServerName]" port="[PortNumber]" protocol="[Protocol]"></TeamFoundationServer> </Settings> 

You specify the name of your Team Foundation Server, the port number (most likely 8080), and the protocol (either http or https).

So, for the example, after making the appropriate changes, the settings.xml file should look like this:

 <?xml version="1.0" encoding="utf-8"?> <SourceControlConverter> <ConverterSpecificSetting> <Source name="VSS"> <VSSDatabase name="c:\MyVSS"></VSSDatabase> <UserMap name="C:\Convert\UserMap.xml"></UserMap> </Source> <ProjectMap> <Project Source="$/VSSTest.root" Destination="$/MyConvertedVSS></Project> </ProjectMap> </ConverterSpecificSetting> <Settings> <TeamFoundationServer name="SSRTM" port="8080" protocol="http"></TeamFoundationServer> </Settings> </SourceControlConverter> 

You are using the UserMap.xml file located in the C:\Covert directory. You are converting to the MyConvertedVSS Team Project, so you added that to the Destination attribute. And you have added the appropriate Team Foundation Server settings for your server.

You are now ready to run the conversion.

Converting and Viewing Results

To start the conversion, go back to the command prompt you opened earlier, and while still in the C:\Convert directory:

1. Run the following:

    vssconverter migrate settings.xml 

2. You are asked if you want to start the migration. Press Y to start it. You are then asked for the VSS administrator password (again, for this example, the password is blank, so simply press Enter). The conversion continues. Once the conversion is complete, you will be notified of the success or failure of the process.

3. VSSConverter uses SQL Express during the migration process. If the conversion process uses more than 4GB, it will fail. You fix this by using SQL Server instead of SQL Express, and adding the following tag to the <Source> tag:

    <SQL Server="SQLServerName"></SQL> 

When the conversion is finished, it writes out a report to the file VSSMigrationReport.xml, as shown in Figure 12-22.

Figure 12-22

This report gives you the details of the conversion, including any possible warnings or errors that may have occurred, so you know what to look for in Team Foundation Server.

Of course, the true test of the conversion will be to see it in Team Foundation Server. Once you have converted the example, open Team Explorer, and navigate to the MyConvertedVSS Team Project. Double-click the Source Control icon in the project to open Source Control Explorer. You can then drill down into the MyConvertedVSS folder, and verify the files have been converted, and the history has been maintained, as shown in Figure 12-23.

Figure 12-23

There you go, you have successfully migrated a Visual SourceSafe project into Team Foundation Version Control!

Using CS-Converter to Convert Visual SourceSafe

As you have seen, Microsoft provides a free tool, VSSConverter, for converting your Visual SourceSafe information over into Team Foundation Version control. One drawback of the tool is that it is completely command-line driven, requiring you to run the conversion from the command prompt, as well as edit XML configuration files by hand. Another potential issue is that the VSSConverter application can only be used to convert Visual SourceSafe projects, so users of other version control systems, such as Subversion or CVS, must find other means to convert their information into TFS.

One solution is to make use of the Team Foundation Server Object Model, and create a customized tool for running the conversion. However, if you do not want to go that route, there are some third-party tools on the market that will do the conversion for you. One of these tools is CS-Converter, by ComponentSoftware (componentsoftware.com).

CS-Converter is a graphical conversion tool, which can be used to migrate a variety of version control systems, including Subversion, CVS, and Visual SourceSafe, onto Team Foundation Version Control. One of the main benefits of a tool such as CS-Converter is that it is a graphical conversion tool, making it easier to use by a majority of people. Another benefit is that it is able to convert so many different other systems to Team Foundation Version Control.

According to the help file for CS-Converter, it has several advantages of VSSConverter. For example, when converting the information, it keeps the original check-in timestamp, instead of updating the timestamp to the conversion date. It also provides the ability to graphically map user names from VSS to TFS, by selecting the appropriate user from a drop-down list box.

The CS-Converter help file does a great job of providing a step-by-step example of converting from VSS to TFS, so you won't go into that here. If you are interested in a graphical tool for converting Visual SourceSafe, or need a tool to convert from Subversion or CVS, it is recommended you investigate this product more on your own. Figure 12-24 shows a screenshot from CS-Converter.

Figure 12-24