Migrate from TFVC to Git

Background

This guide outlines the steps required to migrate your repositories from Microsoft’s TFVC into Git-based repositories.

IMPORTANT : Since TFS 2015 and Azure DevOps both support Git-based repositories, this doesn’t force your teams to move away from them!

Here are the available Git hosting services:

In this guide

  1. Prerequisites
  2. Create Remote Git Repository
  3. Clone TFVC to Local Git Repository
  4. Connect to Remote Git Repository
  5. Push to Remote Git Repository
  6. Additional Improvement
  7. Further Reading
  8. FAQ

Prerequisites

The prerequisites stay the same regardless of where you choose to host your Git repositories (TFS, GCcode or GitHub).

In order to migrate your TFVC repository into a Git repository you will need:

Create Remote Git Repository

First up, you will need to create a new Git repository in your Git hosting service (TFS 2015, GCcode or GitHub).

The process will be different depending on the hosting service selected by your team. However, it remains simple and effortless as long as you have the appropriate permissions to create repositories.

Create Remote Git Repository in TFS

  1. Open the web portal for your TFS team project in a browser.
  2. Navigate to the CODE section using the navbar.
  3. Open the list of repositories by clicking the small down arrow ↓ beside your TFVC repository.
  4. Click + New repository....

    Create Repo in TFS - Step 4

  5. By default, Git should already be selected as the Type. If not, pick Git from the list.
  6. Enter the name of your new Git repository. (i.e. my-git-repo)

    Create Repo in TFS - Step 5

  7. Finally, click Create.

Create Project in GCcode

  1. Open GCcode in a browser.
  2. On the right side of the navbar, click the + (New) menu and select New project.

    Create Repo in GCcode - Step 2

  3. Enter the name of your new project (i.e. Git Playground). This will automatically fill out the Project slug. The project slugs are URL-friendly versions of project names.
  4. Pick your team’s GCcode project for the Project URL field.
  5. Select the appropriate level of visibility for the project.

    IMPORTANT : Keep in mind that GCcode is only accessible on the Government of Canada network. Therefore, Public means available to other departments and agencies. For more information about visibility, see “Subgroups - internal organizations”.

  6. Finally, click Create project.

Create Project in GitHub

Steps will be added shortly.

Clone TFVC to Local Git Repository

  1. Open a PowerShell terminal.
  2. Create a folder for your local repositories (i.e. C:\sources) and navigate into that folder.

     mkdir c:\sources
     cd c:\sources
    
  3. Download the latest Visual Studio .gitignore template from GitHub into this folder. A .gitignore file specifies intentionally untracked files that Git should ignore. To read more about .gitignore files, see Ignoring Files of the Pro Git book.

     Invoke-WebRequest -Uri https://raw.githubusercontent.com/github/gitignore/master/VisualStudio.gitignore
     -UseBasicParsing -OutFile .gitignore
    
  4. Add patterns to match files, folders or branches from your TFVC repository in TFS that should be ignored during this migration process. Good candidates for this include any installers, archived release branches, etc. To read more about the patterns to match items, see Git ignore patterns from Atlassian.

     dev-tools-installers/
     releases/
    
  5. Create a folder to clone your Git repository into (i.e. C:\sources\my-git-repo) and navigate into that folder.

     mkdir c:\sources\my-git-repo
     cd c:\sources\my-git-repo
    
  6. Clone your TFVC repository from TFS to a local Git repository. Don’t forget to specify the .gitignore file that you copied earlier!

     git tfs quick-clone "https://ado.intra.dmz/ProjectCollection/" "$/DevCoP-CdpDev" . --gitignore="c:\sources\.gitignore"
    

    IMPORTANT : There is a bug with the latest version of the libgit2/libgit2sharp library being used by git-tfs which reports an unhandled System.AccessViolationException exception. However, this is thrown during the clean-up phase after the migration which doesn’t affect the clone process. You can read more about this on the issue page for this bug.

  7. Add a .gitignore file at the root for your solution.

     Invoke-WebRequest -Uri https://raw.githubusercontent.com/github/gitignore/master/VisualStudio.gitignore
     -UseBasicParsing -OutFile .gitignore
    
  8. Remove secrets or encrypt as necessary.

Connect to Remote Git Repository

In order to push your local repository to your selected Git hosting service, it needs to know where the remote repository is located. This is done by adding a remote in with a Git command. To read more about remotes, see Working with Remotes from the Pro Git book.

The following steps will help you find the URL to your remote Git repository.

Copy remote repository URL in TFS

  1. Open the web portal for your TFS team project in a browser.
  2. Navigate to the CODE section using the navbar.
  3. Open the list of repositories by clicking the small down arrow ↓ beside your TFVC repository.
  4. Navigate to your project’s page by clicking on its name.

    Find repo URL in TFS - Step 4

  5. Click the Copy to clipboard button.

    Find repo URL in TFS - Step 5

Copy remote repository URL in GCcode

  1. Open GCcode in a browser.
  2. Filter the projects to find the one your are looking for.
  3. Navigate to your project’s page by clicking on its name.

    Find repo URL in GCcode - Step 3

  4. Click the Clone button on the right side of the screen.
  5. Click the Copy URL to clipboard button.

    Find repo URL in GCcode - Step 5

Copy remote repository URL in GitHub

Steps will be added shortly.

Connect local Git repository to remote Git repository.

  1. Use the URL that you copied from the previous section to connect your local repository to the remote one.

     git remote add origin "https://ado.intra.dmz/ProjectCollection/DevCoP-CdpDev/_versionControl"
    

Push to Remote Git Repository

  1. Push local Git repository into remote Git repository.

     git push --all origin
    
  2. Enter your Windows credentials as requested. If you make a typo, simply press CTRL + C to cancel the command and try again.

    Push to Git Repo - Step 2

    TIP : Press the up arrow ↑ to bring back the last command from the terminal’s history.

Additional Improvement

Productivity tips for your repository.

Further Reading

Learn about Git

Similar Guides

FAQ

Is it possible to migrate the code changeset history from TFSV to Git?

Did you succeeded? Should we do that?

It is possible, and we have successfully done it a few times. You can use the GitTFS tool.

There is no legal requirements for us to keep source code history, therefore we do not recommend keeping any history in the conversion. We don’t see any value in keeping it because the code is the truth of how the project functions currently (features and bugs included). If something needs to be changed, it still needs to be changed whether it was codded a specific way in the past for a reason or not. If the team still is set on keeping history, we suggest you only keep history going back one release, as the conversion will take a very long time.

Would you recommend to use the Wiki functionality for replacing our current SPECS document using MS Word?

I saw multiples interesting functionalities like the ReadMe.md (i.e.: for the file project configuration) and the Wiki section in markdown.
Personally, I see a lot of pros to use GitLab. Centralize everything, any docs at the same place.

Absolutely!!

All documentation should be, at a minimum, moved into source control. This allows you to version your documentation with the code it’s documenting. Taking it a step further to change your documentation to markdown is even better. That will allow you to track changes through your documentation, and allow you to begin to automate the documentation.

Wikis should be used to document client or user information while documentation related to development or deployments should be kept with the source code itself. You should also feel free to not use the Wiki itself at all, if all the documentation is in the source control. If you are not using a Wiki, any client or user documentation should be published to a website; GitLab Pages and GitHub Pages are both great services to host this type of documentation.

What are the real benefits of using Git into a long term perspective?

Actually, we are working with TFS and everything works fine. Why should we move to Git? What are the real benefit in short term and long term?

Even if Git is hard to start with at the begining, there is so much pro in short and long term.

The branching model

Communuties and third party tools