Workspaces

What is a workspace?

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.