Effortless TFVC to GIT Migration Guide: Tips for a Smooth Transition

While working for a client who had a TFVC (Team Foundation Version Control), I was challenged to migrate a project from Team Foundation Version Control hosted in Azure DevOps to Git on Bitbucket. Although I lacked sufficient experience and knowledge, I embraced the opportunity and accepted the challenge. TFVC is a centralized version control system from Microsoft that allows companies to track and manage changes in source code, having only one point in a server to host historical data and developers having only a copy on their PC.

Like commits in GIT version control, in TFVC we have “changesets”, which are information about changes to a file at a specific moment. Changesets contain information like who did the change, when it was done, what file was changed, and if any comments were added. One of the challenges in the mentioned project was migrating the entire history of 1,120 changesets from the repository’s creation in 2018 until today, and we later found out that exporting this would be the most time-consuming task.

In this article, we will go through the necessary steps to perform TFVC to GIT migrations seamlessly using the GIT-TF tool.

Why Migrate To Git?

There are many reasons why companies decide to migrate their TFVC projects to Git; these are some of them:

• Flexibility and Collaboration: Git offers a distributed version control system, allowing developers to work offline and collaborate more efficiently. It provides a branching model that makes it easier to manage and merge code changes.
• Branching and Merging: Git’s branching and merging capabilities are more robust, enabling teams to work on features, bug fixes, and releases simultaneously without disrupting the main codebase.
• Faster Performance: Git’s local setup is faster for operations than TFVC’s centralized model.
• CI/CD Integration: Git is compatible with modern CI/CD pipelines for streamlined development.
• Industry Standard: Git is the most popular standard for version control.

Looking For The Right Tool

One of the easiest ways to perform a migration is from the TFVC portal by following the steps in this video. This portal can only handle up to 180 days of history, but our project had more than three years, so we could not use it, and we needed to look up alternatives.

When searching for tools to support the migration, the most popular tool that we found was GIT-TFS, a tool that helps bridge the gap between two version control systems: Git and Team Foundation Version Control (TFVC). We did a test with it, and it worked well for a test repository. However, when we tried to clone our real project to a local Windows Machine, we got countless errors related to the Maximum Path Length Limitation. The Maximum Path Length Limitation is a restriction in Windows that defines the maximum number of characters a path can contain. This limit is set at 260 characters. For example, the path C:\Users\user.name contains 18 characters. However, if the total path length exceeds this limit (260), migration errors may begin to occur. We have also identified another tool, GIT-TF, which does not have this character limit.

Then, if your project has a big folder structure, my recommendation is to use GIT-TF, which does not have this limitation. So, if you are using Windows and you decided to use GIT-TFS, perhaps you could find several errors when cloning the repository. Let’s begin with the steps to perform a migration using GIT-TF and GIT.

Prerequisites

This is the list of prerequisites you need to fulfill to complete the migration process from TFVC to Git:

• A TFVC project in a TFS repo.
• A Bitbucket repo to host migration.
• Git-tf tool installed.
• Git tool installed.

The Migration Process

Now that the requirements for the migration are clear, we are going to proceed with the actual migration process from TFVC to Git.

Cloning The TFVC Repository

The initial and crucial step for the project's success is to clone the TFVC repository, ensuring including the necessary parameters to guarantee the cloning of all changesets. The duration of this step will directly depend on the size of the repository and its history.

To clone a TFVC repository to our local machine, ensuring all the changesets history, we need to execute the following command:

git-tf clone http://tfsurl/tfs/DefaultCollection $/project C:\destination — deep

Replace "http://tfsurl/tfs/DefaultCollection” with your repo URL, "$/project” with the name of your project or branch to clone and "c:\destination” with the path in your PC where you should clone. This step can take several minutes to end; be sure not to interrupt it before it ends.

Important: be careful to use the "-deep” parameter to ensure changesets history is present in the cloning process.

After the last step is finished, we can see in the console the number of cloned changesets. This is important to ensure that the repository has been successfully cloned and that we have all changesets ready to migrate to Bitbucket. It’s a good idea to do a list export with all changesets to compare against Bitbucket’s commit list when the migration is complete. The command to export a list is the following:

git log — pretty=format:”%H %d” > changesets.txt

This command will export to a text file called changesets.txtthe list of all cloned changesets with two important fields, %H is the hash of the commit and %D that is the changeset identifier of TFVC. The file will be saved in the path where the command is executed. Now, we are ready to export the project to a Bitbucket using GIT.

Performing The Migration

So far, we have been working with GIT-TF to clone the repo. Now we need to work with Git to push this project to the Bitbucket repository. The first thing that we need to do is to configure the Bitbucket repository as a remote repository in our local repository. To accomplish this, we have to run the following command:

git remote add <remotename> <https://username@bitbucket.org/Project>

Replace <remotename> with whatever name you want to give your local remote; generally, we use “origin”. Replace <https://username@bitbucket.org/Project> with the URL of your Bitbucket repo where the project will be migrated.

The next step is to do a push to Bitbucket. To accomplish this, execute the following line:

git push -all <remotename> -f

Replace <remotename> with the same name that you added in the previous step.

The -f parameter is to ensure that the code will be migrated without considering whether the destination has any files and -all is to ensure that all the changesets will be migrated to bitbucket as commits.

When this step is completed, we can export a list of commits that we have now in Bitbucket to compare the number of changesets vs commits. To achieve this, we can use the following command:

git log — pretty=oneline > commits.txt

Now, we have two text files containing the complete list of commits. We can validate if there are any differences by comparing the two files to ensure that all changesets have been migrated. Now we have two files to validate that all changesets were migrated successfully to Bitbucket.

After following the previous steps, we migrated a TFVC project to Bitbucket.

Conclusions

In this article, we have learned about one method to migrate projects from TFVC to GIT using GIT-TF, mitigating the issues that would appear when we need to perform a migration of a set of changesets that is bigger than 180 days, avoiding the Windows restriction when we have a long path in files structure on our projects using GIT-TFS.

TFVC is a suitable option for scenarios where your development team is small or specific security requirements need to be met. For instance, if you require a more personalized RBAC model or desire complete control over the infrastructure hosting your code. TFVC excels in configuring robust branching and merging policies compared to Git. Therefore, if these features align with your requirements, TFVC stands out as a solid choice, but when our code grows and new developers join the team, working with TFVC can be a headache.