Please carefully review the scenarios and limitations below before using this tool.

This tool is not appropriate for all migration scenarios and should not be used for upgrade scenarios (i.e. upgrading an existing TFS 2005 server to TFS 2008). For more information on upgrading an existing TFS instance, see the official guidance in the Team Foundation Installation Guide.

If you’ve reached this page, you have probably found yourself in need to migrate some number of team projects from one TFS instance to another. If the upgrade process included with TFS (see Installation Guide) doesn’t cover your scenario, and backup/restore isn’t the right process either, this tool may be able to help. There are limited number of scenarios in which this tool is recommended, and there are also several limitations and guidelines to consider before using this tool. It is strongly recommended that you fully understand all of the following limitations of this tool before using it to migrate data.


  • 1) This tool is limited to migrating only Version Control items, Work Items, and the links between them. Other portions of Team Projects are not migrated by this tool, including Reports, Team Build data, and Sharepoint content.
  • 2) Work Item IDs and Changeset numbers will not be preserved during migration. New IDs are assigned sequentially as items are migrated, so any references to these IDs will be invalid after migration. As work items and changesets are migrated, the links between those items will be migrated correctly, despite the ID changes.
  • 3) Timestamps on work item revisions and changesets will be updated to the time of migration. Any work item fields that store date time information will have their values correctly migrated, but the time of the revision will not be migrated. The most significant impact this has on a system is in reports that rely on a time dimension (i.e. Bug Trends, Code Churn). Because the migration typically occurs over a much shorter time span than the original operations, the time axis in such reports will effectively be compressed.
  • 4) Some branching and merging scenarios may not be migrated correctly. While there have been efforts in the latest release to make the migration of branches and merges more robust, there are still a large number of cases which have not been tested. The release notes contain some additional information about the branch and merge cases with known issues.
  • Review the Release Notes for the latest release to get information about the specific issues/limitations.

Guidelines / Alternatives

  • In many situations, the TFS to TFS Migration tool is not the only option, nor it is the ideal solution. The following are several other options that may be employed in place of the migration tool.
  • Upgrading from TFS 2005 to TFS 2008 should be done using the processes specified in the Team Foundation Installation Guide.
  • Backup and Restore should be considered before using this tool. An example of how this may be used is for the entire server backup to be restored on a second server, followed by a destroy of the team projects that are not needed on the second server, leaving only those that were to be migrated. This approach will preserve timestamps as well as Team Project data outside of version control and work item tracking.
  • The Team Foundation Server Proxy should be used in cases involving remote development with TFS. MSDN contains more information on using the TFS Proxy for remote development.

Recommended Scenarios

  • While there are alternative options for many scenarios, there are some scenarios in which the TFS to TFS Migration Tool is recommended. Please keep the above limitations in mind before using the tool in one of the following scenarios.
  • Consolidating Team Projects that reside on multiple TFS instances. Remember that only the Version Control and Work Item Tracking data will be migrated.
  • Copying Version Control and Work Item Tracking data to another server. Be sure to evaluate Backup and Restore in these cases.
  • Mirroring Version Control and Work Item Tracking data between two servers. Note that the first step in a mirroring session is to migrate the items from the "source" server (mirroring is simply an option that is specified for a session to continue synchronizing changes after the migration).

Quick Links


Frequently Asked Questions (FAQ's)

Feedback and Support

Visual Studio Team System Links

Last edited Dec 17, 2009 at 4:11 PM by mmitrik, version 2


No comments yet.