Any application written to use the Windows crypto APIs will have access to that root certificate, and will consider your TFS deployment to be trusted. Applications using the Windows certificate store include Internet Explorer, Google Chrome, and Visual Studio 2013. However, Git for Windows (git.exe) uses OpenSSL for its crypto stack, and the Git for Windows distribution includes a set of trusted root certificates in a simple text file. Your organization’s root certificate will not be in this list, and if you try to use git.exe to perform network operations against your TFS server, you’ll get an error like this:

F:\>git clone https://myserver/tfs/DefaultCollection/_git/Proj
Cloning into 'Proj'...
fatal: unable to access 'https://myserver/tfs/DefaultCollection/_git/Proj/': SSL certificate problem: unable to get local issuer certificate

You have a couple of different options for how to work around this problem. The easy way is to just disable SSL certificate validation entirely – if this is what you want to do, you can find numerous articles on the web about how to do this. I won’t address it here because unfortunately, it defeats one of the purposes of having SSL to begin with – server authentication. Your organization probably has HTTPS turned on for a reason. What if we wanted to add the root certificate to git.exe’s certificate store, in the same way that domain membership in your organization has added it to your Windows certificate store? Here’s how.

Step 1. Extract the root certificate as a base64-encoded X.509 CER/PEM file

(These steps were written using Internet Explorer 11. On other versions of IE, I suspect the same steps are still possible, but they may be slightly different.) Open Internet Explorer and visit your TFS server in the web browser. For our example above, the URI would be https://myserver/tfs. At the right of the address bar is a lock icon which you can click to learn more about the details of how your connection to the server has been secured.

At the bottom of the drop-down is a link to “View certificates.” If you click the “Certification Path” tab of the dialog box which comes up, you can see the entire chain of trust. Select the top-most certificate in the chain – this is the root certificate.

Then click “View Certificate” to open up that root certificate, and go to the Details tab.

On the Details tab, you can select “Copy to File…”, which will start the export wizard for certificates. On the second page of the wizard, you will be asked what format to use for exporting your certificate. Choose the second option: base64 encoded X.509.

Save the certificate somewhere on your disk. You’ll need this for step 2.

Step 2. Switch to using a private copy of the Git root certificate store

When you install Git for Windows (msysgit) on your machine, it drops a file called curl-ca-bundle.crt in your Program Files directory. This is the root certificate store for git.exe. It’s just a text file containing all of the certificates that git.exe trusts, one after another. The text file has UNIX (\n) line endings, though, so if you open it up in Notepad, it won’t look too pretty.

What we want to do in this step is to make a copy of the curl-ca-bundle.crt file (which is installed on a per-machine basis) that will be private for just your Windows user. The ideal place to store the file is in your %USERPROFILE% (C:\Users\yourname) directory, right alongside your per-user (“global”) .gitconfig file. On my machine, the following command does it – if you are using 32-bit Windows, you’ll want to fix up the Program Files part of the path so there isn’t an “x86” section.

(If you don’t know where your user profile directory is, you can just run “echo %USERPROFILE%” at the command prompt. For example, mine is C:\Users\phkelley.)

copy "C:\Program Files (x86)\Git\bin\curl-ca-bundle.crt" C:\Users\yourname

(Note: In the Git for Windows 2.x series, the path has changed to C:\Program Files (x86)\Git\mingw32\ssl\certs\ca-bundle.crt. Thanks Craig for the tip.)

Next, we’ll want to configure Git to use this private copy of the certificate store. You can set this up with the following command:

git config --global http.sslCAInfo C:/Users/yourname/curl-ca-bundle.crt

(Note the use of forward slashes and not backslashes above.) As a quick sanity check, try to clone a repository from GitHub to make sure that everything is still working:

git clone https://github.com/libgit2/EmptyGitRepository

Step 3. Add the exported root certificate to the private copy of the store

The last step is to open up the curl-ca-bundle.crt file (the private copy we made in step 2) in a text editor and add an entry at the bottom for your exported root certificate. I used the “unix2dos” tool available here to change the line endings in the file from \n to \r\n so that I could open the file up in Notepad:

unix2dos C:\Users\yourname\curl-ca-bundle.crt

Then I opened up the exported certificate from step 1 in Notepad and put its entire contents onto the clipboard.

Next, I opened up the C:\Users\yourname\curl-ca-bundle.crt file, added an entry for this certificate at the end, pasted in the cert, and saved the file. All done!

Step 4. Try it out…

F:\>git clone https://myserver/tfs/DefaultCollection/_git/Proj
Username for 'https://myserver': domain\username
Password for 'https://domain\username@myserver':
remote:
remote:                    fTfs
remote:                  fSSSSSSSs
remote:                fSSSSSSSSSS
remote: TSSf         fSSSSSSSSSSSS
remote: SSSSSF     fSSSSSSST SSSSS
remote: SSfSSSSSsfSSSSSSSt   SSSSS
remote: SS  tSSSSSSSSSs      SSSSS
remote: SS   fSSSSSSST       SSSSS
remote: SS fSSSSSFSSSSSSf    SSSSS
remote: SSSSSST    FSSSSSSFt SSSSS
remote: SSSSt        FSSSSSSSSSSSS
remote:                FSSSSSSSSSS
remote:                  FSSSSSSs
remote:                    FSFs    (TM)
remote:
remote:  Microsoft (R) Visual Studio (R) Team Foundation Server
remote:
Receiving objects: 100% (6781/6781), 47.12 MiB | 32.56 MiB/s, done.
Resolving deltas: 100% (4553/4553), done.
Checking connectivity... done

Not bad! The steps above for adding a root certificate apply to anyone using git.exe in corporate/self-signed scenarios like this, not just Team Foundation Server 2013 or later.

An endpoint for a clone, fetch, push, or pull operation in Git is called a “remote.” Visual Studio 2013’s Git support contains support for remotes using the following protocols.

• HTTP (i.e. https://github.com/libgit2/TestGitRepository, or https://yourname.visualstudio.com/DefaultCollection/_git/YourRepo)
• File paths (i.e. F:\myrepo.git, or \\servername\sharename\myrepo.git)
• git:// URIs

As of this writing, Visual Studio 2013 does not have support for ssh-based remotes. If you have a Git remote that uses SSH and you try to perform a network operation in Visual Studio, you’ll get the message “This transport isn’t implemented. Sorry.” (This message comes from the libgit2 library.) I don’t have a timeline for when support for SSH remotes might be implemented in Visual Studio.

HTTP endpoints

When performing network traffic against an HTTP endpoint, Visual Studio uses the System.Net stack (HttpWebRequest and friends) to actually issue the web requests. Both HTTP and HTTPS URIs are supported.

The System.Net stack in the .NET framework has full support for web proxy configuration through the Internet Options page. If you need to use a web proxy to communicate with your remote endpoint, you should set up your proxy configuration there. Start the Control Panel, then select Internet Options to open the Internet Properties dialog. On the Connections tab, at the bottom of the page is a button labeled “LAN settings.” Clicking this button opens the proxy configuration dialog for Internet Explorer.

The System.Net stack also includes support for proxy authentication (HTTP status code 407), if your environment requires it.

Special considerations for HTTPS endpoints

If an HTTPS URI is used for a remote, the Windows certificate store is used to validate the server’s SSL certificate.

If the server to which you are pushing/pulling has a self-signed certificate, then as of this writing, we give an unfortunate and vague error message to the user. “An error occurred while sending the request” is what is commonly seen. You should use the Windows certificate manager (certmgr.msc) to add the self-signed certificate (or the authority at the top of the certificate’s chain) to the Windows certificate store as a trusted certificate, and then try your network operation again. We hope to improve on this user experience in a future release, because it is very hard to make the mental jump here from “an error occurred” to “oh, I need to add the certificate to my certificate store.”

Visual Studio 2013 also supports the use of client certificates as part of the SSL negotiation, if the server requires it. Certificate selection is automatic, by default. If you need to use a specific client certificate to prove your identity to the server, you can use the command-line “tf certificates” command to select which client certificates are eligible for presentation.

Authentication

When using HTTP to communicate with a remote, Visual Studio may be required to authenticate with the remote server. Visual Studio 2013 supports 3 methods of authentication when communicating with a Git server over HTTP.

• Basic authentication
• Integrated Windows authentication
• Team Foundation Service federated authentication (used only when communicating with endpoints at https://*.visualstudio.com/)   

Each authentication method has its own credentials acquisition dialog.

Basic authentication

If you are communicating with a third-party Git hosting service like Github or Bitbucket, you will probably be using Basic authentication to send your password in cleartext inside the SSL tunnel. Visual Studio 2013 is able to store and retrieve basic auth credentials from the Windows credentials vault using the same protocol as the Windows Credential Store for Git. If you have this plug-in for Git for Windows installed, then once you save your credentials once, you should be able to use both git.exe and Visual Studio to perform network operations without any password prompts.

If you ever want to clear the password from storage, you can use the Credential Manager in the Control Panel to remove it, or use cmdkey.exe from the command line.

Windows authentication

If you are using an on-premises Team Foundation Server 2013 server to host your Git repository, then you probably authenticate to it with integrated Windows authentication. If you are logged on with your domain account, authentication from Visual Studio should be transparent.

However, git.exe (which uses CURL for its transport layer) will not be able to retrieve your credentials transparently. You can either type your DOMAIN\username and password strings when you push/pull, or you can install the Windows Credential Store for Git and persist your credentials for git.exe’s use.

Most customers do not use HTTPS to secure their Team Foundation Server 2013 server on their intranet. However, if your organization does use HTTPS, and has its own certificate infrastructure used to sign the certificate for the Team Foundation Server 2013 deployment, then you may find git.exe fails to validate the SSL certificate. This is because the root certificate for your organization’s certificate infrastructure is pushed to your machine’s Windows certificate store through Active Directory, but git.exe cannot see it. Git for Windows uses OpenSSL for its certificate store and the set of certificates comes with the Git for Windows package. You can disable SSL verification for git.exe through your .gitconfig file, or use the http.sslCAInfo and http.sslCAPath configuration options to help Git for Windows find the certificate at the root of the certification chain for your TFS 2013 deployment.

Federated authentication

This authentication mechanism is used only by the Team Foundation Service (https://*.visualstudio.com/) and is based on Windows Live ID. If you have already logged into your Team Foundation Service account using the Team Explorer, you should find that authentication for push, pull, clone, and fetch operations is transparent.

The command-line Git for Windows executable, git.exe, does not support this authentication method. If you want to perform network operations against a Team Foundation Service-based Git repository using git.exe, you will need to provision a basic authentication username and password using the Edit Profile dialog in the Team Foundation Service web interface. You can then use that basic auth username and password from the command line. (Visual Studio will still prefer to authenticate using federated authentication.)

With each major release of Visual Studio, customers find that they have to re-build their check-in policies for TFS version control to target the new version of the client object model. As the pace of Visual Studio major releases has quickened (there will be both a Visual Studio 2012 and a Visual Studio 2013!) customers have been experiencing this pain more often. We also often receive questions about how to manage deployment of check-in policies in mixed environments, where some users have Visual Studio 2010, and some have Visual Studio 2012, but both versions of Visual Studio need to use a custom check-in policy developed in-house.

Example multitargeted checkin policy solution

Today we are releasing an example solution which demonstrates two nifty things:

1. How to use a single code base for your custom check-in policy, but build that check-in policy for Visual Studio 2010, 2012, and 2013 simultaneously.
2. How to deploy your check-in policies to customers using VSIX packages, which are easy to install.

You can download the solution from here. (Updated 27 August 2015)

How does it work?

You can open this solution in VS 2010, VS 2012, or VS 2013. In the toolbar of Visual Studio you will see a Configuration drop-down that allows you to select what “target” version of the TFS Version Control client object model to use for the build – 2010, 2012, or 2013. When you say Build, the appropriate version of the client object model is used to create a check-in policy DLL. So if you selected VS2012_Release, then you would get a DLL in the bin\VS2012_Release directory that is suitable for installation on VS 2012 clients.

If you have the Visual Studio SDK installed for whatever version of Visual Studio you’re using, then the solution will automatically detect this, and in addition to the DLL in the bin\VS2012_Release folder, you get a VSIX you can distribute to your clients to install on their machines. If you don’t have the Visual Studio SDK installed, we notify you with a build warning: “The Visual Studio SDK is not installed, so no VSIX installer package can be generated.” The Visual Studio SDK is a free download – it’s about 10 megabytes and is specific to each version of Visual Studio. (Be careful when getting it for VS 2010 – if you have Service Pack 1 installed, then you need to make sure to get the “VS 2010 SP1 SDK” which is a different download.)

If you have a fully mixed environment, and you want to build your custom check-in policy for VS 2010, VS 2012, and VS 2013, then you’ll need a machine with all three of those Visual Studio versions installed side-by-side, and you’ll need the Visual Studio SDK installed for each one. Then when you’re ready to produce a VSIX installer for your clients, open the solution in each Visual Studio version one at a time. Make sure that the appropriate Configuration is selected in the toolbar (VS2010_Release for VS 2010, VS2012_Release for VS 2012, etc.) and do a build. At the end of the process, in your bin directory, you’ll have three VSIX installers – one for each version of Visual Studio. Distribute these installers to your users so that they can install the check-in policy. VS 2010 users get the VS 2010 VSIX, VS 2012 users get the VS 2012 VSIX, and so on.

How do I adapt the solution to my existing custom check-in policy’s codebase?

You’ll probably want to start by doing a giant search-and-replace on the strings ExampleMultitargetedCheckinPolicy and MultitargetedCheckinPolicy to replace them with your check-in policy name and namespace. Don’t be afraid to open up the .csproj file in Notepad to make changes to it.

Also, be sure to update the VSIXMANIFEST files so that your VSIX extension gets the right company name, new GUIDs, and your own description of the check-in policy. The PKGDEF file contains the registry entries that are added by the VSIX that allow the check-in policy to be discovered by Visual Studio, so it should be updated too, to reflect the new namespace and name of your check-in policy, and the name of the DLL file your solution is producing.

Downsides to VSIX deployment

One downside of VSIX deployment of check-in policies is that they are not visible outside of Visual Studio. If you’re using the TF.exe command line, Git-TFS, or the Windows Explorer shell extension for TFS, then the check-in policy will not be available in those environments, and you’ll have to override it in order to check in. If you need the check-in policy available in these environments, VSIX deployment is not for you, and you should deploy your check-in policy via the traditional method:

1. Put the DLL file for the check-in policy somewhere on disk
2. Add a registry value of type REG_SZ to “HKLM\SOFTWARE\Microsoft\VisualStudio\[version]\TeamFoundation\SourceControl\Checkin Policies” that points to the check-in policy DLL
3. (VS 2012 and later only) Run devenv /setup from an elevated command prompt so that the check-in policy is visible to Visual Studio

If you’re not going to use VSIX deployment, then you don’t need the Visual Studio SDK installed, and you can just ignore the build warning that says the VSIX installer is not being generated.

What causes this error?

As mentioned in a previous blog post, local workspaces keep certain pieces of data for your workspace on your local machine. With server workspaces, these data are kept on the server. These local pieces of data include your working folders (mappings), your local version table, and your pending changes.

Under our current architecture, only a single operation (thread) can use this local data at a time. If two pieces of system want to use the data store simultaneously – perhaps the Solution Explorer and the Source Control Explorer both want to refresh after an Undo operation was performed – then these two components have to take turns to use the local data store. One will wait for the other to finish, and who gets to go first is arbitrary.

The ‘loser’ of the race has to wait before proceeding, but will only wait for about 45 seconds. If he ends up waiting for that full amount of time, but still doesn’t get the chance to use the local data store (because some other component of the system is still using it), then this error will be raised.

Depending on the scenario in which the error was raised, it may be benign. In the example I described, where two components of the system are both trying to refresh simultaneously, and one fails with a TF400030 timeout error, then it’s possible to manually refresh (F5) the offending component and move on with your work.

However, it’s also possible for this error to pop up during an operation you care more deeply about, like a check-in, or a merge, or an undo operation. In these cases seeing this error may be more of a real problem than a minor annoyance.

45 seconds is a long time. What’s taking so long?

There are 3 main possibilities.

The first possibility is that the ‘scanner’ is doing a full scan of the workspace to detect pending edits. This involves looking at the file attributes of each item in the workspace and comparing its size and last-modified time to our previously-observed values in the local version table. This scanner is what enables local workspaces to detect edits created just by opening up a file in Notepad and saving it to disk without ever telling TFS. Full scans are infrequent, but they always happen at application startup, and they may happen again later if a flood of changes comes in and overwhelms our notification-based ‘partial scanner’, causing a full invalidation.

The cost of scanning the disk is proportional to the number of items in the workspace, and is strongly affected by whether or not the operating system’s disk cache is hot or cold. A cold full scan (for example, after you reboot your machine) is much more expensive because actual I/O has to be performed to get the file attributes of each item in the workspace. Cold full scan performance is strongly affected by the performance of your I/O subsystem – SSDs are dramatically faster at random I/O than mechanical disks.

The second possibility is that the user is performing a ‘reconciled’ operation on the server. Since the client’s copy of the working folders, local version table, and pending changes are authoritative, when performing a server-side operation like check-in, shelve, or merge, the server’s copy of this data must first be synchronized with the client’s. Our synchronization protocol is incremental and efficient for working folders and the local version table, but to assure absolute correctness, we copy the entire pending changes table up to the server if any change has occurred since the last reconciled operation.

The cost of reconciling is therefore proportional to the number of pending changes in the workspace, and is strongly affected by the bandwidth of your connection to the TFS server and the performance of that TFS server – the speed at which it can complete the reconcile.

A third possibility for a slowdown is a deadlock between two operations – such a deadlock would not be related to the number of items in the workspace, and would be highly-scenario specific. Such issues are bugs. We fixed a couple of deadlock scenarios in Visual Studio 2012 Update 2, especially related to installing and uninstalling NuGet packages.

How can I reduce the frequency of this error or avoid it entirely?

First, please ensure that your copy of Visual Studio 2012 is updated to Update 2 or later. This ensures that you are protected from the deadlock scenarios described above.

Second, try to avoid working with extremely large sets of pending changes (10,000+) for a long time without checking in. This helps to keep ‘reconcile’ costs low.

Third, and this is probably the most important point to look at – keep the size of your workspace from growing too large. For Visual Studio 2012, we are recommending that local workspaces have 50,000 or fewer items. (‘Items’ means both files and folders.) The actual enforced limits are much higher (500,000 items) but as you increase the size of your workspace, the risk of seeing TF400030 errors increases as it takes longer for the scanner to complete a full scan.

Fourth, the problem is exacerbated by having multiple instances of Visual Studio 2012 open at the same time, especially if they have the Source Control Explorer open. Refreshing the Source Control Explorer is an operation which requires reconciling with the server – if you make a change in one instance of Visual Studio, all other instances are notified of the change and refresh themselves. This increases contention for the local data store.

Lastly – if you have exhausted all options and find you are still receiving the TF400030 error, you can switch your workspace from “local” to “server” in the Edit Workspace dialog. It is not possible to get a TF400030 error when working with a server workspace.

How can I find out how many items I have in my workspace?

Measuring this is made more complicated than it could be because of the backup copies of each file that we keep to support offline diff and offline undo.

Most workspaces are singly-rooted – that is to say, there is some local folder C:\MyWorkspace where everything is underneath that path. If you right-click on that path in Windows Explorer (now called the File Explorer) and go to Properties on that folder, you should be able to see the total number of items in that folder (recursively). This count ends up double-counting files, though, because the backup copies in our hidden $tf folder are being counted twice!

A slightly more accurate measure is to turn on the ability to see hidden files and folders, and then run the same Properties command in the File Explorer on the C:\MyWorkspace\$tf folder. This won’t count folders, so we’re undercounting slightly, but it should be clear whether you are greatly exceeding the recommendation of 50,000 items, or whether you’re generally in compliance with the recommendation. (The recommendation of 50,000 items is fairly conservative.)

I’m over the recommended limit - how do I reduce my item count?

Often customers have more than one branch of their source code mapped in the same workspace. There is some guidance here for how to start using multiple workspaces – one for each branch.

Some customers, though, will find that their codebase is simply too large for local workspaces. In this case we recommend that you switch from local workspaces to our more traditional ‘server workspaces,’ which are proven to scale to up to 10,000,000 items in a single workspace (given appropriate server hardware).

What is Microsoft doing to make this better in the future?

We are planning to include, in the next major version of Visual Studio, a built-in feedback mechanism that warns you when you greatly exceed the recommendation for the number of items in a local workspace.

The next major version of Visual Studio also includes significant performance enhancements for the ‘scanner’ component. The performance improvements are not algorithmic, but are rather the result of careful performance (and memory allocation) tuning and profiling. The performance improvement in the next release of Visual Studio for the scanner, at scale, is about a factor of two. As a result we will likely be adjusting our guidance for the number of items in a local workspace upward from 50,000 to some larger number for the next release of Visual Studio.

The Manage Workspaces dialog

Let’s look first at the Manage Workspaces dialog, which is used to look at all the workspaces on the current machine.

The Manage Workspaces dialog can be accessed through the following methods.

1. File menu –> Source Control submenu –> Advanced –> Workspaces…
2. Launch the Source Control Explorer. On the toolbar, there is a “Workspace:” combo box. Open the combo box and select “Workspaces…”.
3. (In Visual Studio 2012 and later.) Open the Pending Changes Page in the Team Explorer. From the Actions menu, select “Manage Workspaces.”

The Manage Workspaces dialog shows, by default, those workspaces on the local computer to which you have access. Most of the time that means that the workspaces belong to you. But if you’re on a shared machine and someone has created a public or public-limited workspace, then those workspaces will show up in this list as well.

You can check the “Show remote workspaces” checkbox at the bottom to refresh the list of workspaces and have it show instead all workspaces, on any machine, where you are the owner of the workspace.

From this dialog box, you can add new workspaces, delete existing workspaces, or edit workspaces you already have to change their properties. The properties which you can change are summarized in a previous blog post on workspaces.

Switching between workspaces

You may recall that each workspace has its own set of working folders (also called mappings) and pending changes. The Source Control Explorer and Pending Changes Page in the Team Explorer each allow you to switch between workspaces so that you can see and manipulate the pending changes in each workspace. (In Visual Studio 2010 and earlier, the Pending Changes toolwindow also allows you to switch between workspaces.)

This screenshot shows the controls which allow you to select your workspace in the Source Control Explorer and in the Pending Changes Page of the Team Explorer. All the workspaces on the local machine to which you have access are available in either drop-down.

When you select a different workspace, you may notice that the Source Control Explorer’s left and right panes have some items change from grey to black, or black to grey. This is because the workspace you switched to may be mapping more items, fewer items, or an entirely different set of items with its working folders. The Local Path hyperlinks above the right pane may change accordingly as well.

In the Team Explorer’s Pending Changes Page, when you select a different workspace, the set of pending changes, your pending check-in comment, associated work items, etc. will all switch as well. Everything is preserved; you can toggle right back when you want to. Keep in mind, though, that a solution cannot span multiple workspaces and is always ‘in’ a particular workspace.

Scenarios for using multiple workspaces

Many customers using TFS version control use branching and merging to control code movement and perform servicing on existing releases. For example, there might be a Main branch located at $/Project/Main, and several branches for different releases also located underneath $/Project, such as $/Project/Release1, $/Project/Release2. Often there is also a development branch called $/Project/Development.

Customers commonly create just one workspace on your machine that maps $/Project to a location on disk like C:\Project. In the example described above, that results in all four branches coming down to the local disk in the same folder. The engineer who does this might be working almost exclusively in the Development branch, and they end up having 4 times as much source code downloaded to their machine. If they end up having to make a change in the Release2 branch to fix a production issue, they will find their pending changes for Development ‘mixed in’ with their Release2 changes.

It’s much less error-prone to compartmentalize the branches by creating one workspace for every branch. In this particular scenario the customer might create four workspaces, instead:

This allows work to go on in each branch separately. If you are in the middle of a change in Development but are interrupted and have to make a change in Release2, then just close your copy of the solution from the Development branch and open your copy from the Release2 branch. This action will automatically switch the Pending Changes Page and Source Control Explorer’s workspaces to match the solution’s workspace. All your work from Development is still there and untouched; you can use the Release2 workspace to commit your change there, and then switch back to Development just as easily as you switched to Release2.

Performing integrations

Some customers have mentioned that the reason they map all their branches in the same workspace is to perform integrations (merges) from branch to branch. You can still merge when using multiple workspaces described above. You always want to be performing the merge in the target branch – if I’m integrating from Development to Main, then the workspace selected should be PHKELLEY-DEV_Main, since that’s where changes are being pended and that’s the branch to be modified with a check-in. The source branch doesn’t have to be mapped in the same workspace (or mapped at all!).

Performance benefits

If you’re using local workspaces, then you can see some performance benefits by switching to using “one branch == one workspace”. Local workspaces are intended for customers with small to medium size projects where the workspace has 50,000 or fewer items. I have seen customers where each branch of their source code is well within our scalability target for local workspaces – but the customer has placed several branches of source code all in the same workspace. The total number of items then ends up being far beyond 50,000, and performance suffers or “TF400030: The local data store is currently in use by another operation” errors are observed. Simply separating out the branches with a “one branch, one workspace” philosophy brings them back within the scalability target and they end up being much happier.

You might be asking, “What are the differences between local and server workspaces, and where do these two names come from?”

Offline support

If your workspace is a “local workspace,” several key data structures have been moved from the TFS server onto the TFS client. Thus the name “local” – the data structures are local to your machine instead of being hosted for you by the TFS server. Putting these data structures on your local machine gives VS 2012 the ability to perform a number of source control operations without ever calling the TFS server. These operations continue to work when your machine is disconnected from the TFS server.

• Opening a source-controlled solution
• Checking out a file for edit
• Pending a new file or folder for add
• Pending a delete on an existing file or folder
• Pending a rename on an existing file or folder
• Asking “what are the pending changes in this workspace?”
• Undoing pending changes
• Diffing your copy of a file with the version of the file your change is pended against

With a server workspace, all of these operations require a connection to the TFS server. And even with a local workspace, most other operations, such as using the Source Control Explorer, viewing the history of an item, checking in, shelving/unshelving, branching/merging, undeleting items, etc. still require you to have a connection to TFS. But the set of operations which are available offline is actually quite substantial, and frees you up to be able to get some done on an airplane or a train, for example, where a connection to your TFS server or the Team Foundation Service might not be available.

No read-only bit

When using server workspaces (the traditional kind of workspace), every file in the workspace’s working copy that is not checked out for edit/add has the +R bit set. If you want to edit the file, you have to check it out first. In Visual Studio, this is seamless, because typing in the editor automatically checks out the file. (You may experience a slight pause as you type the first character in the document.) The process of checking out the file removes the +R bit and enables you to save your changes to the file to disk.

With local workspaces, this restriction is relaxed. The +R bit is never set on items in your working copy (unless you set it manually!). When Visual Studio asks the TFS version control system “what are the pending changes in this workspace?”, we answer that question not by asking the server for the list of all items which have been checked out, but by scanning the working copy on disk and looking for items which the user has edited.

This means that with a local workspace, you can pull up a source-controlled file in your favorite non-Visual Studio editor, make a change, save the file, and then immediately see your pending edit on the item reflected in the Pending Changes Page of the Team Explorer. No explicit checkout is necessary.

Detected changes (or ‘candidate’ changes)

While edits in a local workspace can be pended implicitly just by editing the file, adds and deletes still must be explicitly pended. However, TFS version control’s workspace scanner also detects new files which are ‘candidates’ for addition, and missing files and folders which are candidates for deletion. The Team Explorer’s Pending Changes Page has a link which shows the number of detected adds and deletes, and provides a link to the Promote Candidate Changes dialog which can be used to pend ‘real’ adds or deletes on these items. This is called “promoting” the candidate adds and/or deletes – because they become real pending changes.

Detected candidate adds can also be ignored from this dialog so that they no longer show up. Your .tfignore file will be updated to include an exclusion which applies to the items you have ignored. If you do not have a .tfignore file, one will be added for you.

Invisible to VS 2010 and earlier

Because local workspaces use a local data store that only VS 2012 and later know how to read and write, local workspaces are invisible to VS 2005, 2008, and 2010 clients which might be installed on the same machine as your VS 2012 instance. If you want to share your workspace between VS 2012 and VS 2010 on the same machine, then local workspaces aren’t for you and you should convert your workspace back to a server workspace so that VS 2010 can see it.

No enforcement of PendChange permission or checkout locks

Because local workspaces allow users to pend and undo pending changes without ever calling the TFS server, these mechanisms for restricting when an item can be checked out are ineffective in local workspaces. Checkin locks still work just fine, but the act of taking or releasing a checkin lock requires a call up to the TFS server.

Converting to and from local workspaces

The “Edit Workspace” dialog can be used to change your workspace type from local to server, or vice versa. The setting is in a combo box marked “Location.” You will need to click the “Advanced >>” button at the bottom of the dialog in order to see the combo box. Once you have made your selection for workspace location (local or server), click OK to make the change effective.

Converting from a local workspace to a server workspace is a fairly quick operation. Going from server to local can take up to a few minutes to complete because backup copies of each file in your workspace are taken and saved off in a hidden folder. These backup copies are required to support offline undo and offline diff operations, neither of which would be possible without a backup copy to undo back to, or a backup copy to compare against.

Performance and scalability

As mentioned above, local workspaces keep a backup copy of each file in the workspace. These copies are compressed, but typically this means that a local workspace takes up about 50% more space on disk than an equivalent server workspace. If disk space is a concern for you, server workspaces may be more appropriate. These backup files are deleted when converting your workspace from local to server.

Local workspaces have scalability limitations due to their use of the local workspace scanner which checks for edited items. Local workspaces are recommended for most of our customers, because most workspaces fit into the “small” or “medium” category in our view – that is, they have fewer than 50,000 files and folders. If your workspace has more than 50,000 items, you may experience performance problems or TF400030 errors as operations exceed 45 seconds in duration. In this case, splitting your workspace up into multiple smaller workspaces (perhaps one workspace per branch), or switching to server workspaces is recommended.

Server workspaces are optimized for performance at large scale and can support workspaces with up to 10,000,000 items (provided your SQL Server hardware is sufficient).

Default workspace location

The default workspace location (local or server) for your Team Project Collection can be changed by launching the Team Explorer and going to the Settings page. Under “Team Project Collection,” select “Source Control.” On the “Workspace Settings” tab, you can change the default workspace type from local to server or vice versa.

TFS version control has two main objects to interact with.

1. The version control server. There is exactly one of these in every Team Project Collection, and it’s shared by everyone.
2. Your workspace – this belongs to you. You can have as many workspaces as you would like.

Your workspace is the ‘owner’ or ‘container’ of a variety of important artifacts.

1. Your working folders, or “mappings” – these declare what portions of the version control server will be brought to your local disk to create your working copy. You can have a workspace without any working folders – but without any, you’re saying that you want to have an empty working copy, which isn’t very useful. An example of a mapping might be “$/Project -> C:\Workspaces\Project”.
2. Your pending changes. When you want to make changes to the version control server’s copy of the source code, you pend your changes against your working copy. When you have finished preparing your changes, you check in from the workspace to the version control server. You can also shelve your pending changes to create a ‘shelveset’ on the server, or unshelve someone else’s pending changes into your workspace to use them temporarily or to check them in.
3. Your conflicts, if you have any.
4. (Advanced topic!) Your local version table – while the working folders define what you want your working copy to look like, the local version table describes what the working copy looks like ‘right now.’

In addition to owning the artifacts above, workspaces have a variety of properties.

1. Each workspace exists on a particular version control server.
2. A name – the default name is the name of your computer.
3. An owner – an identity known to Team Foundation Server.
4. A comment field in which a description of the workspace can be stored.
5. Each workspace exists on a particular computer name.
6. Each workspace is either a server workspace or a local workspace.
7. Files downloaded to the working copy can either have their last-modified date set to the time of download (default) or to the last check-in date of the file.
8. Workspaces are permissioned objects – by default, they are private, meaning only the owner can use them.

Each of the properties described above can be changed, except for the version control server on which the workspace exists. That particular property of the workspace is immutable.

Workspace names

• The maximum length of the workspace name is 64 characters.
• Workspace names are unique for each owner (on each version control server). That is to say, I can have a workspace named HELLO_WORLD, and you can have a workspace named HELLO_WORLD, but neither one of us can have two workspaces named HELLO_WORLD. Generally it’s best to think of the uniqueness constraint as applying to the name;owner combination, which we also call a ‘workspacespec’. Under this scheme, it’s easy to see that the workspacespec “HELLO_WORLD;DOMAIN\You” is different from “HELLO_WORLD;DOMAIN\Me”.
• The default name for a workspace is the name of the computer on which it was created. If that name is already taken, a “_1” or “_2”, etc. is appended onto the end of the name until an available name is found.

Workspace owners

• The owner of a workspace is the identity who created the workspace.
• When changing the owner of a workspace, the identity receiving ownership does not get a chance to reject acquisition. It is a gift which that identity must accept.
• Depending on the situation, the caller may lose all permissions (except Read) to the workspace after changing the owner. Most workspaces are ‘private’ and only grant Use, Checkin, and Administer permissions to their owner.
• The “Edit Workspace” dialog will not let you change the owner and the permissions of the workspace at the same time.
• Prior to TFS 2010, the owner of a workspace cannot be changed.

Workspace comment

• The workspace comment is a string with essentially unlimited length. We will let you store up to 2^30 characters in the workspace comment. However, I believe that some of the earlier versions of TFS may restrict the comment length to 2,048 characters.
• The comment field is blank by default.

Computer name

• Each workspace exists on a particular computer. The computer name field can be up to 31 characters long, and this property is set for you automatically.
• The TFS server does not do anything with this data other than persist it, and allow clients to use it as a query filter. For example, the query “tell me all the workspaces I have access to on this machine" is very common.
• In certain situations, you may want to change the computer name of an existing workspace. For example, if you change your computer name, you may need to update the computer name on all your workspaces. Another scenario is moving a detachable volume (for example, a virtual hard disk) from one machine to another. As long as the local paths of the items stay the same (you mount the volume with the same drive letter), then you can update the computer name of the workspace, and immediately continue using it.
• Functionality for changing the computer name of a workspace is limited to the command line only – the “/computer:newcomputername” switch to the “tf workspace” command allows you to specify a new computer name. This switch is new in Visual Studio 2010.
• You can update the computer name for a set of workspaces by using the “/updateComputerName:oldcomputername” switch of the “tf workspaces” command. Note carefully that this is a different command – ‘tf workspaces’ – and that this switch requires you to specify the old computer name. The new computer name is inferred from the machine on which you run the command. This command has existed since Visual Studio 2005 and is intended for use in the scenario where you rename your computer.

Workspace location

• Starting with TFS 2012 and Visual Studio 2012, workspaces have a “Location” property. A workspace’s location can either be “server” or “local.”
• Local workspaces are new in TFS 2012 and Visual Studio 2012. All workspaces on TFS 2005, TFS 2008, and TFS 2010 servers are server workspaces.
• If your “Edit Workspace” dialog doesn’t show the workspace location combo box (you may need to click “Advanced >>” to see it), then your client must be Visual Studio 2005, 2008, or 2010, which don’t support local workspaces. This means your workspace is a server workspace.
• If your “Edit Workspace” dialog does show the workspace location combo box, but it is not editable (it is permanently set to “Server”), then your client is Visual Studio 2012 or later and does support local workspaces. However, your server is older than TFS 2012 and does not support them.
• There is a long list of differences between server workspaces and local workspaces – enough to fill several blog posts. I hope to blog on this topic in the future.
• If your server and client both support local workspaces, then you can freely convert between the two by changing the setting in the combo box and clicking OK to commit your changes to the workspace. The conversion process can take some time; going from local to server is quicker than going from server to local. There is a progress dialog which is shown during this conversion.

Last-modified date

• When you do a “Get” in TFS version control to update your working copy, files are downloaded from the server and placed on your local disk.
• Each file on your local disk has a last-modified date. In Visual Studio 2005, 2008, and 2010, the last-modified date of downloaded files is not set to any special value. It gets set to whatever the current time is at the time the file is downloaded.
• Starting in Visual Studio 2012 and TFS 2012, you have the option to change the last-modified date setting from “Current” to “Checkin”. This setting is hidden behind the “Advanced >>” button in the “Edit Workspace” dialog.
• Just like with local workspaces (above), you need both Visual Studio 2012 or higher and TFS 2012 or higher in order to change this setting to “Checkin.”
• If set to “Checkin,” then downloaded files (not folders) will have their last-modified time set to the date and time that the item was checked into source control. There is a small performance cost to enabling this feature.
• When you change this setting on an existing workspace, the items you already have downloaded will not have their last-modified times instantly updated. You will need to perform a “tf get /all” in order to get them all set correctly.
• Most customers do not need to set this setting to “Checkin,” but some have custom workflows or build orchestrations that require the last-modified dates to be set this way.

Workspace permissions

• Starting in TFS 2010, workspaces are permissioned objects. There are four permissions on workspaces – Read, Use, Checkin, and Administer.
• If you have Read permission on a workspace, its existence and its properties (including its local version table and pending changes) are visible.
• If you have Use permission on a workspace, you can create and undo pending changes, update the local version table, shelve pending changes, etc.
• If you have the CheckIn permission on a workspace, you can check in the pending changes from the workspaces.
• If you have the Administer permission on a workspace, you can modify the properties of the workspace in the “Edit Workspace” dialog, or delete the workspace.
• The owner of the workspace always has all permissions on the workspace.
• All valid users of the Team Project Collection have Read permission on all workspaces. (This is subject to change in future releases of TFS.)
• Instead of providing a full permissioning UI experience, the “Edit Workspace” dialog lets you pick between a set of predefined “permission profiles.” The default is “private workspace”, where only the owner has permissions on the workspace.
• Other profiles include Public-Limited and Public – in these profiles, permission to Use, Checkin, and/or Administer are extended to all valid users of the Team Project Collection. These permission profiles are useful if you want to have a machine with a single workspace, shared by multiple users.
• You can read more about workspace permissions in this blog post.

Let's say that in our Team Project Collection we have one Team Project ($/Proj), and two branches -- $/Proj/Main and $/Proj/Dev. And let's also say that we have a workspace which maps $/Proj/Main to C:\MyWorkspace. Our source tree is pretty small -- we only have 5 files, named a.cs through e.cs. I've done a get, and so when I look in C:\MyWorkspace, this is what I see:

C:\MyWorkspace>dir
Volume in drive C is Physical Disk 1
Volume Serial Number is BA8F-FF44

Directory of C:\MyWorkspace

05/18/2012  01:41 PM    <DIR>          .
05/18/2012  01:41 PM    <DIR>          ..
05/18/2012  01:41 PM                14 a.cs
05/18/2012  01:41 PM                54 b.cs
05/18/2012  01:41 PM                 5 c.cs
05/18/2012  01:41 PM               115 d.cs
05/18/2012  01:41 PM                17 e.cs
               5 File(s)            205 bytes
               2 Dir(s)  60,134,879,232 bytes free

Let's also say that my co-worker, John, has made a change in the Dev branch to c.cs. He's really added a big chunk of code in the Dev branch, and so the c.cs file there is much bigger. But he hasn't changed any of the other four files. The other four files are exactly the same in Dev and Main.

Furthermore, for some reason (maybe John and I need to work more closely together now) I need to switch my workspace from mapping the Main branch to having the Dev branch. The way I would do this is through the "tf workspace" dialog.

Change the server path mapping only, from $/Proj/Main to $/Proj/Dev. Leave the local path part (C:\MyWorkspace) the same.

When you click OK, you'll be prompted to do a get.

If I say yes, a regular get will be performed, and everything will work fine -- but the get will be inefficient. Let's watch what happens when I click yes.

C:\:
Getting MyWorkspace
Deleting C:\MyWorkspace\a.cs

C:\MyWorkspace:
Getting a.cs
Deleting C:\MyWorkspace\b.cs
Getting b.cs
Deleting C:\MyWorkspace\c.cs
Getting c.cs
Deleting C:\MyWorkspace\d.cs
Getting d.cs
Deleting C:\MyWorkspace\e.cs
Getting e.cs

Each item is deleted and re-downloaded as part of the switch from $/Proj/Main to $/Proj/Dev. Even the four items that are identical in the two branches are redownloaded, which is not a good use of time.

Let's look at what would have happened if I had said "no" to the dialog, and then run a "tf get /remap".

C:\MyWorkspace>tf get /remap
Deleting C:\MyWorkspace\c.cs
C:\MyWorkspace:
Getting c.cs

You can see that no action was taken for the four items which are identical. As a result no time was expended downloading these four items unnecessarily.

Why not run “tf get /remap” all the time? Nothing bad would happen if you were to do so. However, adding the /remap switch does increase the amount of work done by the server to process your request. As a result, it is not on by default.

In TFS 2010, we’ve added new features related to the process of checking in, but we didn’t want to create more and more overloads of the Workspace.CheckIn method to support them. As a result, in 2010 we’ve added a single new overload that takes a WorkspaceCheckInParameters object.

public int CheckIn(WorkspaceCheckInParameters checkinParameters);

The legacy methods from TFS 2005 and 2008 are still present and fully supported. But you may find that flags and settings related to new features of TFS 2010 (such as gated check-in) are only available through the WorkspaceCheckInParameters overload.

Put simply, the WorkspaceCheckInParameters object encapsulates all the necessary information to complete a check-in from a workspace. Here’s a simple example which checks in all pending changes, with a provided comment.

WorkspaceCheckInParameters wcip = new WorkspaceCheckInParameters(myWorkspace.GetPendingChanges(), “My changeset comment!”);
myWorkspace.CheckIn(wcip);

The above example is equivalent to the following call that uses one of the older CheckIn() overloads. In simple cases like this, we don’t expect that you’ll go to the trouble of using a WorkspaceCheckInParameters object. There’s no advantage to it in this case.

myWorkspace.CheckIn(myWorkspace.GetPendingChanges(), “My changeset comment!”);

An advanced example

The constructors on WorkspaceCheckInParameters are intentionally limited. If we were to go down the road of implementing constructor overloads for every possible combination of flags and parameters, we would have put ourselves back in the same place we started – a nightmare situation of dozens of overloads. Instead, the model we’ve taken is to provide reasonable defaults on the WorkspaceCheckInParameters object. You can then adjust whatever flags and parameters are needed for your scenario before calling Workspace.CheckIn.

Here’s a more complex example which tries to commit a changeset on behalf of another user, and bypasses gated check-in if any of the pending changes being committed are to paths protected by a gated build definition.

WorkspaceCheckInParameters wcip = new WorkspaceCheckInParameters(“My comment!”);
wcip.PendingChanges = myWorkspace.GetPendingChanges();
wcip.Author = “CONTOSO\ClarkKent”;
wcip.OverrideGatedCheckIn = true;
myWorkspace.CheckIn(wcip);

You’ll find that this call will fail if you don’t have permission to override gated check-in, or permission to check in on behalf of another user. (It will also fail if the user CONTOSO\ClarkKent doesn’t exist. J)

Checking in a shelveset directly

One new feature in TFS 2010 is the ability to directly check in a shelveset. In previous releases, customers were required to unshelve the shelveset into a workspace and check in from there. To support this feature we’ve added new methods to the VersionControlServer object.

public int CheckInShelveset(String shelvesetName, String ownerName);
public int CheckInShelveset(ShelvesetCheckInParameters shelvesetCheckInParameters);

There is some intentional parallelism here with the Workspace.CheckIn methods. The first method is likely to be the most commonly used, just as the older, non-WorkspaceCheckInParameters methods are likely to be the most commonly used workspace check-in methods. For advanced scenarios, you can instantiate a ShelvesetCheckInParameters object, adjust the flags, and then call CheckInShelveset.

Here’s an example which checks in a shelveset BugFixes;CONTOSO\ClarkKent and then deletes the shelveset if the check-in successfully completes.

ShelvesetCheckInParameters scip = new ShelvesetCheckInParameters(“BugFixes”, “CONTOSO\ClarkKent”);
scip.DeleteShelveset = true;
myVersionControlServer.CheckInShelveset(scip);

Since the Author property of the ShelvesetCheckInParameters was not specified in this case, the changeset resulting from this check-in will be attributed to the user who called CheckInShelveset, not the owner of the shelveset. Additionally, the requested deletion of the shelveset only occurs if the calling user has CheckinOther permission for the items in the shelveset. (This is so a non-privileged user cannot go around causing others’ shelvesets to disappear.)

One of the new features of TFS 2010 is automatic version control proxy configuration. The first time a version control operation is executed, the client contacts the server and asks for proxy configuration information. If no proxy is available for the client, it will ask again after 24 hours have passed.

To allow proxies to be auto-configured by location, the client provides to the server its “site name” from Active Directory. This data is used by the server to determine which of several proxies to assign the client to. Clients in Germany can be assigned to the Germany proxy, and clients in South Africa to the South Africa proxy. This is the same mechanism that Windows uses with the Add Printer Wizard to show printers physically close to you.

Unfortunately, there is a bug in the automatic proxy configuration mechanism of the VS 2010 client when communicating with a 2005/2008 server. When used against an older server, no query can be made to auto-configure a proxy because the server does not support the functionality. But the site name from Active Directory is still retrieved, on every version control operation from the list below.

• Get
• Merge
• Unshelve
• Edit
• Delete
• Undelete
• Rename
• Undo
• Add
• Branch
• Resolve

In all cases, there is some performance penalty for retrieving this data from LDAP. But in some cases it can be particularly bad. One customer reported a delay of 8 to 9 minutes to retrieve the site name from Active Directory. Fortunately, there is a workaround available for this issue. If you are using VS 2010 against a TFS 2005/2008 server, you may notice an increase in performance by disabling automatic proxy configuration through the use of the following registry settings.

Check your version control proxy settings in Visual Studio first, by going to Tools –> Options –> Source Control –> Visual Studio Team Foundation Server. If you have a proxy configured, your proxy server protocol, name, and port will be available there, and you should not be affected by this issue. (If you want to be 100% sure, instructions for verifying your proxy settings are below.)

No version control proxy:

These settings are for users who are not using a proxy server. All files are downloaded from the central TFS server directly.

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\TeamFoundation\SourceControl\Proxy]
"Enabled"="False"
"Url"="https://dummy.example.com/"
"AutoConfigured"="False"

Manually configured version control proxy:

You should not have to take any further action. If you like, you can inspect your registry settings to ensure they look like those below. (If you happen to have “LastCheckTime” or “LastConfigureTime” values in addition to these values, that’s normal and they are harmless.)

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\TeamFoundation\SourceControl\Proxy]
"Enabled"="True"
"Url"="https://yourversioncontrolproxy:8081/"
"AutoConfigured"="False"

Installing the workaround settings

Copy/paste the text into Notepad, save it as a .reg file, and execute it. You’ll be prompted to authorize the merging of this data into the registry. Be sure to restart Visual Studio for the changes to take effect.