Git-TFS - Work with your Team (Foundation Server) with Git

Matt Burke, GitHub, http://pickardayune.com/

Git-tfs is an open source two-way bridge between Microsoft Team Foundation Server (TFS) and git, similar to git-svn. It fetches TFS commits into a git repository and lets you push your updates back to TFS.

Web Site: http://git-tfs.com/
Current Version: 0.17.1
License & Pricing: Open Source (MIT), Free
Documentation:
Wiki: https://github.com/git-tfs/git-tfs/wiki
Support:
Mailing list: http://groups.google.com/group/git-tfs-dev/
Issues: https://github.com/git-tfs/git-tfs/issues
IRC: #git-tfs on freenode
Project : https://github.com/git-tfs/

I am a source control geek. Keeping versions of my code and being able to reliably synchronize it between computers is something I can't do without. So it shouldn't be a big surprise when I admit that, once upon a time, I was excited to use CVS. I was subsequently thrilled to use Clear Case, Subversion, and TFS.

When I first learned about distributed version control tools (for example Mercurial or Git), I was quickly won over by the ability to version anything, anywhere, without ever needing to set up a server. This was exactly what I needed for my side projects. It allowed me to keep a history of changes regardless of whether I was online, and I could synchronize my changes later.

Being able to work offline got me interested in Mercurial and Git, but being able to quickly and easily experiment was what really hooked me. One of the big advantages of a distributed version control system (DVCS) is its ability to sanely handle branches. Every time you create a workspace, you have created a branch. When everything is a branch, there is a lot more focus on making merging as frictionless as possible. This makes "what if?" experiments cheap and easy.

Introducing git-tfs

While I was learning about Mercurial and Git, my employer was using Team Foundation Server (TFS). The git-tfs project was born as an experiment to see if I could use Git while my co-workers continued to use TFS.

git-tfs is a client-side command-line tool, inspired by git-svn. git-tfs provides a two-way bridge between a local Git repository and a TFS server. git-tfs allows you to do your local development in a Git repository, and still synchronize your work with a TFS server.

In this article, I'll walk through some of the things that you can do with git-tfs. I assume that you use or are familiar with TFS source control.

Installing git-tfs

Before you start, you'll need to install the Team Foundation client tools (Team Explorer). You probably already have this installed if you're working with source code in TFS. git-tfs works with the VS2008, VS2010, and VS2012 versions of the Team Foundation client tools.

If you use the chocolatey package manager, you can simply run cinst gittfs. This takes care of downloading git-tfs and its dependencies, and making them available at a command prompt.

You can also download the latest release as a ZIP file. The prerequisites for git-tfs are the .NET 4 Framework and Git (msysgit is recommended). Download the latest release of git-tfs from git-tfs.com. Extract the ZIP file, and add the resulting directory to your PATH environment variable. Verify that git-tfs is installed correctly by opening a new command prompt and type git tfs --version.

The source code is available on GitHub.

Clone

Start by cloning your TFS project into a Git repository. You'll need to know the TFS project collection URL (if your server is TFS 2010 or later) or the TFS server URL (if your server is TFS 2008 or 2005). Git-tfs also needs to know the path in TFS that you want to clone. It can clone any path (other than the root), so you can clone an entire TFS project, or just one subdirectory of it. Use this command to create a Git repository in local-dir.

> git tfs clone https://your-server/tfs/collection $/Project/Path local-dir

The new clone includes the full history of $/Project/Path.

If you have a large TFS repository, a full clone will take a long time to create. To get started more quickly, you can create a Git repository with a snapshot of the latest version from TFS.

> git tfs quick-clone https://your-server/tfs/collection $/Project/Path local-dir

Both clone and quick-clone produce a normal Git repository. Run git log to see the imported commits. While you're developing in this repository, use normal Git tools to commit, branch, etc.

Fetching new changesets

As other developers check in new source code to TFS, you'll want to fetch the changes.

> git tfs fetch

The above command will fetch changes for the current TFS server. It stores all TFS changes on a branch named tfs/default. You can merge the changes from TFS with git merge tfs/default.

To fetch and merge all in one command, run

> git tfs pull

Share using a shelveset

If this is the first time that you're trying out git-tfs, make a commit or two in your Git repository and try creating a TFS shelveset from git-tfs.

> git tfs shelve this-comes-from-git-tfs

This tells git-tfs to collect the changes you've made into one shelveset. You can view the contents of the shelveset using the normal TFS tools.

This is an easy way to get started with git-tfs, because it doesn't create a permanent record (i.e. a changeset), but you can still get a good idea of what it is doing.

Share a single changeset

Git-tfs includes two ways to convert Git commits into TFS changesets. The first is git tfs checkin. This command will create a single TFS changeset with a squashed diff of all of your local Git commits.

For example, consider a repository with one commit (A) that git-tfs created from a TFS changeset (C1), and two commits (B and C) created locally with Git.

A(C1) -- B -- C

To check in the cumulative diff between A and C:

> git tfs checkin -m "made some changes"

Git-tfs can include checkin meta data. For example, to add a work item reference, use the -w flag.

> git tfs checkin -w 1234 -m "made some changes"> git tfs checkin -w 1234:associate -m "made some changes"

More options can be found by running git tfs help checkin.

To use TFS's graphical checkin dialog:

> git tfs checkintool

The checkin or checkintool command will add a TFS changeset (C2) and a corresponding Git commit (D).

A(C1) -- B -- C -- D(C2)

Share all your commits

The second way to convert Git commits into TFS changesets is git tfs rcheckin. This command will create a TFS changeset for each Git commit that you have made locally.

Git-tfs creates the checkins in a single command invocation, so it relies on information in the commits' messages for other commit metadata. The Git commit message becomes the TFS checkin comment. Other metadata can be provided on lines with certain keyword prefixes. For example, a line that starts with git-tfs-work-item: specifies the work item number to link to the new TFS changeset. See the git-tfs wiki for an example and for a list of other fields that can be provided.

A(C1) -- B -- C

Given the previous example of one TFS commit and two local Git commits, you can run this.

git tfs rcheckin

Git-tfs creates TFS checkins from your local commits, and updates your local branch to point to these new commits.

A(C1) -- B(C2) -- C(C3)

TFS branches

TFS source control has branching support. In TFS, a branch looks like another folder in your project. Git-tfs includes the ability to map TFS branches to Git branches. The easiest way to get started with this is to clone the root TFS branch, along with the option that tells git-tfs to retrieve all child branches:

> git tfs clone --with-branches https://tfs/collection $/project local-dir

The repository that git-tfs will create is still a normal Git repository, and you should be able to interact with TFS in the same way that you have before, with the exception that you will need to tell git-tfs which branch you're working with more of the time. For example, to fetch changesets for all of the TFS branches:

> git tfs fetch --all

To fetch changes just for one branch:

> git tfs fetch -i yourbranch

To rcheckin or checkin just one branch:

> git tfs rcheckin -i yourbranch> git tfs checkin -i yourbranch

Sharing a git-tfs repository

If Git starts to catch on with your team, you may find yourself sharing a repository that you created with git-tfs. When you do this, your teammates may also need to use git-tfs to interact with TFS. To enable this in a cloned Git repository, git-tfs can look through the history of the HEAD branch to find TFS configuration information.

> git tfs bootstrap

If bootstrap fails to configure the TFS connection correctly, you can configure it manually with git tfs init. You can provide the same options to git tfs init that you would provide to git tfs clone. For example:

> git tfs init http://server/collection $/project/folder

Conclusion

If you're using TFS and are considering Git, git-tfs can help you get started without a wholesale conversion. If part of your team wants to collaborate with each other using Git, git-tfs can provide a link back to the rest of the team that is using TFS. If your entire team wants to move to Git, but you still have tooling or processes that require the use of TFS, git-tfs can provide the link. And if you end up switching completely to Git, git-tfs makes the transition significantly simpler.

---

More .NET Resources

• .NET Tutorials and Videos

---

Click here to view the complete list of tools reviews

This article was originally published in the Summer 2013 issue of Methods & Tools