When should I use the TFS to TFS Migration Tool?

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.


  • 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.
  • 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.
  • 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.
  • 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.

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).

There may be other scenarios where this tool may be useful, these are the core scenarios that are recommended for this tool. If you have questions or feedback, please post on the Discussions page.

Last edited Dec 17, 2009 at 4:15 PM by mmitrik, version 6


spiegdon Aug 4, 2009 at 3:46 PM 
Here is a scenario that I would like to know if it is possible (I believe so) and recommended (not sure) to use this tool for. We have a 3rd party vendor that works with our application source code pretty heavily. We are under compliance rules to not allow them direct access to our source control / network. We have established a DMZ network that they can authenticate into and we are thinking about installing TFS to that, and establishing a sync that would pull down their changes into a branch, allowing us to review and merge the bits into our trunk. The work item #'s are not essential, just the source code really. What are your thoughts on this topic?

flixxx Jan 27, 2009 at 7:57 AM 
I was very happy to see someone made an effort to solve this. However, I have a few problems when using the application.
1. As mentioned in the limitations, all history posts are marked with the timestamp of the migration time, but that's a known limitation.
2. ... which is worse. I don't get the latest version, which seems very strange indeed! I get versions of files that are months old. I am migrating from a TFS2005 to a TFS2008, which is NOT recommended, but I had to try, right? Is this the reason for the strange behaviour? I was hoping to avoid upgrading the TFS 2005 before trashing it.

I'm curious as, if the old-version-of-file-problem is related to the TFS-versions, I will upgrade, and try again, but if it's a proper bug, I can't use the tool at all.

Again, thanks for the well aimed effort!

vankirkc Jul 2, 2008 at 6:18 AM 
Backup and Restore does NOT work.