Create and Work With Workspaces
Workspaces map folders in Visual Studio Team Foundation Server to folders on your local computer, which is necessary if you want to work on your team’s version-controlled files. When you first download, or "get", local copies of files from Team Foundation Server, you specify a local folder for them. Although you may not notice at the time, this action creates a default workspace that maps the selected server folder with the selected local folder and saves that mapping.
However, instead of using the default workspace, you can create a workspace manually. This option is the best if you plan to work with version-controlled files often or you plan to work with files in more than one folder.
When you create a workspace manually, you choose specific, version-controlled folders to form a logical, isolated group. You can then perform the following actions on the files that are contained in those folders as a group:
Refresh your local copies to make sure that you have the most recent versions so that you can build and test your changes locally.
Check out files to modify.
Check in, shelve, or undo pending changes.
View the pending changes that other team members have made so that you can anticipate conflicts before you check in changes.
This topic describes workspace terms, demonstrates how to create a complex workspace, and explains common problems with workspaces. For more information about how to get local copies of files or how to add files to version control, see Get the Source for Your Team Project and Add Files to Version Control.
In this topic
Basic Guidelines for Creating a Workspace
Workspace Terms
Get files quickly by using the default workspace
Create a Workspace Manually
Using Multiple Workspaces to Work on Multiple Branches
Troubleshooting Common Problems
Basic Guidelines for Creating a Workspace
When you create a workspace, you should consider the following guidelines:
If you want to work with files from a single folder, map to one that is as close to the level of the team project collection as you can but no closer than you must. That way, you will get all the files that you need without getting many that you do not need.
Create a complex workspace that contains multiple mappings only if you want files from disparate areas in your source-code tree or if you want to use cloaking to restrict the number of files that you get from a folder.
If you work in multiple branches, create a separate workspace for each branch to isolate the branches on your local computer.
If you intend to create a local build to test your changes before you check in the files, map all the files that are necessary for the build, not just those you intend to edit.
Workspace Terms
When you start to work with workspaces, you should understand the roles that are played by local folders, server folders, and the workspace that maps the two.
.png "Map a version control folder to a local folder")
Server folders contain the code and other files for your team project. Team members can share the version-controlled files, track changes to them, and revert to earlier versions of them. To list the server folders for your team project, open Team Explorer, and then double-click Source Control.
Local folders contain files that you "get" or check out from the version-control server to your local computer. When you get a file, you download a read-only copy of it to your local folder. When you check out a file, you download a copy that you can edit. When you save edited files, the changes are saved locally and are committed to the server only when you check in the files.
Workspaces map server folders to local folders. You can create a simple workspace that maps a single server folder to a single local folder, or you can create a complex workspace that includes multiple mappings. If a workspace includes multiple mappings, it groups folders into a single unit upon which you can perform actions, such as getting the most recent versions from the server or checking in changes. To list the mappings for a workspace, open the File menu, click Source Control, and then click Workspaces. In the Workspace dialog box, under Workspace, click the workspace, and then click Edit to open the Edit Workspace dialog box.
Get files quickly by using the default workspace
When you work on files that are under version control in Team Foundation Server, you must use a workspace. When you first download, or "get," local copies of files from Team Foundation Server, you specify a local folder for them. Although you may not notice at the time, this action creates a default workspace that maps the selected server folder with the selected local folder and saves that mapping.
To get files quickly by using the default workspace
Open Visual Studio, and then connect to your team project.
For more information, see Connect to and Access Team Projects in Team Foundation Server.
In Team Explorer, click Source Control.
Note
If you have not previously created a workspace, one is created for you when you open Source Control Explorer. The workspace has the same name as your computer and appears in the Workspace list in the toolbar of Source Control Explorer.
Right-click the team project, folder, or branch from which you want to download local copies of files, and then click Map to Local Folder.
Important
Make sure that you choose a folder high enough in the code tree that you get all the files you need to create a local build but low enough that you are not getting more files than you need.
The Map dialog box opens.
Under Local folder, click the ellipses (…) to browse to a location that you want to use for your local copies of server files.
In the Browse for Folder dialog box, specify a location for your local copies.
For example, you might type C:\.
Click Make New Folder, and type a name for the new folder into which your local copies are downloaded.
For example, you might type Workspaces.
In the Browse for Folder dialog box, click OK.
In the Map dialog box, select the Recursive check box to download all files in the folders under the server folder, and then click Map.
In the message box that appears, click Yes to get the most recent versions of the mapped files.
Create a Workspace Manually
You should create a workspace manually if you plan to work with version-controlled files frequently. A workspace that you create manually can be as simple as a single mapping between the top folder of a team project and a folder on your local computer. In contrast, a workspace can be a complex mapping of all subfolders from one folder, most subfolders from another folder, and selected subfolders from a third folder.
.png "A workspace to map selected files only")
To map all subfolders under a folder, add it to the Source Control Folder column. In the Local Folder column, specify a unique local folder for the local copies of files.
To map some but not all subfolders under a folder, add it on one row, and add all subfolders that you do not want on subsequent rows. In the Local Folder column, specify a unique local folder for the local copies of files. In the Status column, click Cloaked for each subfolder.
To create a workspace manually
Determine which folders you want to work with.
Open Visual Studio, and then connect to your team project.
For more information, see Connect to and Access Team Projects in Team Foundation Server.
In Team Explorer, click Source Control.
Note
If you have not created a workspace, one is created for you and is given the same name as your computer. The workspace appears in the Workspace list in the toolbar of Source Control Explorer.
Review the list of folders in Source Control Explorer, and note which folders and subfolders that you want to work with.
Create a workspace.
On the File menu, click Source Control, and then click Workspaces.
In the Manage Workspaces dialog box, click Add.
Note
You can also click the default workspace and then click Edit if you want to reuse the default workspace.
In the Add Workspace dialog box, type a name for the workspace.
For each folder that you want to map, perform the following steps:
Under Working folders, click the first empty row in the Source Control Folder column, and then click the ellipses (...).
In the Browse for Folder dialog box, click the folder on the server that contains the files that you want to work with, and then click OK.
(Optional) If you want to map some but not all subfolders in a folder, add it on one row and the subfolders that you do not want on subsequent rows. In the Status column, click Cloaked for each subfolder.
Under Working folders, click the first empty row in the Local Folder column, and then click the ellipses (...).
In the Browse for Folder dialog box, click the local folder into which you want to copy the files.
Important
If you keep the structure of your local folders as similar as possible to your server folder structure, your development work will be easier. This strategy is especially important if you frequently use the command prompt. For an example, see the figure in Workspace Terms.
(Optional) Click Make New Folder, and type a name for the new folder where your local copies will be stored.
Tip
You can help keep your workspace mappings easier to work with if you use short names for your local folders.
Click OK.
Using Multiple Workspaces to Work on Multiple Branches
You typically create multiple workspaces to work on two versions of your software at the same time. For example, you may work on an update to version 2.0 as you develop version 3.0. By creating separate workspaces, you isolate the files and help make sure that you are always working on the correct version.
Tip
You can also use multiple workspaces if you work on two areas in a single code base or branch.
To create multiple workspaces, you create each one by following the procedure in Create a workspace manually earlier in this topic.
This figure illustrates that a local user has created a workspace for the FeatureTeamA branch, where the new version is under development, and another workspace for the Version2 branch, which requires an update.
.png "Two workspaces mapped to two local folders")
When you create separate workspaces for each branch, you can display the files in each branch in Source Control Explorer. To display the files that are mapped in each workspace, open the Workspace list, and then click the name of a workspace. The list of folders and files changes so that items in the specified workspace are available, but those in other workspaces are not.
For example, the following figure shows what folders and files are in the TeamA workspace. The Folders pane shows that the server folder that is mapped in the TeamA workspace is enabled and the Version2 server folder, which is not mapped in that workspace, is disabled.
.png "Selected workspace shows mapped folders")
TeamA is the current workspace.
Only the folders or branches that are mapped in the TeamA workspace are available.
If you use separate workspaces, you can also easily show which changes you made in each branch separately in the Pending Changes window. To open the window, open Solution Explorer, right-click your project, and then click View Pending Changes. In the Pending Changes window, open the Workspace list, and then click each workspace to display the pending changes for that workspace.
.png "Changes pending in a selected workspace")
Troubleshooting Common Problems
Two common problems can occur when you use the default workspace instead of creating one manually. The first is that some features may be disabled if files that you want to modify have not been mapped. The second is that the default mappings can become confusing.
You can usually solve these kinds of problems most easily by deleting your current mappings and then following the instructions in this topic to create one or more appropriate mappings
Why are some features unavailable?
Some features are not available if you are viewing files in server folders that are not mapped to local folders. If you have not mapped a folder, you cannot check out a file, delete a file, or create a subfolder. To access these features, you must map the server folder by following the instructions in this topic.
Why does my workspace have a mixture of mappings?
When you add files to version control without creating a workspace manually, you are actually creating a default workspace that maps the folder of origin with the server folder that you specify. Similarly, when you get files without creating a workspace manually, you create a mapping in the default workspace between the server folder and the local folder that you specify.
For example, the following figure shows that a user added Solution1 to version control and specified a server folder in which to store the solution. By adding the solution, the user created a mapping between the local folder from which the solution was added and the server folder. The mapping is associated with the user's default workspace, which is named after the user's computer.
Later, the user gets files from a different project that another team member had added to version control. When the first user specified a local folder to which to copy the files, a mapping was created between the server and the specified local folder. This mapping is also associated with the user's default workspace.
As a result, the workspace has a confusing mixture of mappings. The best way to solve the problem is to delete the mappings and follow the instructions earlier in this topic to create a consistent set of mappings.
Mapping with a mixture of local folders
.png "Mixture of local folder mappings")
The local folder from which the user added files.
The local folder to which the user copied files by performing a Get operation.