This FAQ (frequently asked questions) answers questions that are commonly asked about workspaces by users of the Teamprise plugin for Eclipse. If this FAQ does not answer your question, please send an email to support@teamprise.com and we will include an answer to your question in a future version of this FAQ.
What is a workspace?
The term workspace refers to one of two things: either an Eclipse workspace or a TFS workspace. It’s unfortunate that these two things share the same name, since this is confusing for users who are new to TFS and/or Eclipse. Whenever the term workspace is used, always determine which kind of workspace is being referred to. For the rest of this document, the terms “Eclipse workspace” or “TFS workspace” will be used instead of just “workspace”.
What is an Eclipse workspace?
Every running instance of Eclipse is associated with an Eclipse workspace. This Eclipse workspace serves as a logical container of projects that are available in that Eclipse instance. The Eclipse workspace also has a workspace directory, which is a local directory on the computer that Eclipse is running on. When you first launch Eclipse, you are prompted to choose this directory; it’s also possible to pass the directory as an argument when launching Eclipse to avoid the prompt. The Eclipse workspace directory is also known as the instance location.
The Eclipse workspace directory is the default physical location for new projects that are created in Eclipse. However, it is possible to specify a non-default location for projects. Therefore, the Eclipse workspace is the logical container of all projects for an Eclipse session, but not all projects need to physical be located under the Eclipse workspace directory.
For example, assume that an Eclipse instance is set to use the workspace directory c:\myworkspaces and contains 2 projects: Proj1 and Proj2. Proj1 and Proj2 are both logically contained within the Eclipse workspace associated with the running Eclipse instance. Proj1 uses the default location and is therefore physically located at c:\myworkspaces\Proj1. Proj2 uses a non-default location, say c:\temp\Proj2. Even though Proj1 and Proj2 are logically side-by-side in the Eclipse workspace, physically they are not located side-by-side on disk.
Another purpose of an Eclipse workspace is to store metadata that shoud be specific to the Eclipse instance. This metadata includes many of the preferences that can be configured in Eclipse by choosing the Window -> Preferences menu item. This metadata is stored on disk in a folder called “.metadata” inside the Eclipse workspace directory.
Many Eclipse users choose to use only a single Eclipse workspace for all of their work with Eclipse. Other users will use multiple Eclipse workspaces for many reasons. For example, one strategy is to use an Eclipse workspace per product being worked on. A developer working on two applications App1 and App2 could have two Eclipse workspaces: one containing all of the projects for App1 and the other containing all of the projects for App2. Another common strategy is to use a separate workspace for each branch of a product.
What is a TFS workspace?
A TFS workspace is a collection of data on a Team Foundation server that is used to manage many interactions between a user and the version control portion of TFS. Many version control operations, such as pending a change to a file, must happen in the context of a TFS workspace.
What data does a TFS workspace contain?
A TFS workspace contains the following data:
TFS users who are familiar with some other version control tools may be surprised by the feature of a TF server that tracks local version information for the client side. For instance, suppose you perform a get of a file from a TF server. You then delete this file off disk without notifying TFS. If you perform another get, you may expect to have the file downloaded again, since it is non longer present on disk. However, TFS will not send you the file again, since the local version information for your TFS workspace indicates that the file is already present locally. In this situation, you would need to perform a “force” get – a force get ignores TFS workspace local version information and always downloads the file again.
Why do TFS workspaces exist?
Many version control tools do not have a concept that is similar to TFS workspaces. TFS workspaces offer additional flexibility (if needed) that some other version control tools do not.
Using multiple TFS workspaces allows you to simultaneously work on multiple copies of the same version controlled item on one computer. Another advantage of multiple TFS workspaces is that you can keep multiple pending change sets for unrelated work, instead of a single pending change set containing all pending changes globally.
How are TFS workspaces identified?
Each TFS workspace has a name, an owner, and a computer name. The name is a descriptive name that is specified by the user when creating the workspace. The owner is the TFS user who created the workspace. The computer name is typically the host name of the computer on which the workspace is created.
The name and owner uniquely identify the workspace. For a given owner, all workspace names must be unique, even among workspaces created on multiple computers.
For a given computer name, the local paths of the working folder mappings in a workspace must be unique, even among workspaces created by multiple owners.
For example, assume that there are two TFS users (user1 and user2) who work on two computers (comp1 and comp2). The following examples help to illustrate the TFS workspace rules:
user1 creates workspace work1 on computer comp1. user1 cannot create another workspace named work1 (either on computer comp1 or on a different computer). user2 can create a workspace named work1 (on any computer including comp1).user1 maps the server path $/Proj1 to local path c:\temp\proj1 in workspace work1 on computer comp1. If user2 creates a workspace on the same computer (comp1), user2 will not be able to map any server path to the local path c:\temp\proj1. On a different computer, say comp2, user2 would be able to map to local path c:\temp\proj1.There are some constraints placed on the TFS workspace identifiers. The workspace name is required, must be 64 characters or less, and can’t contain certain illegal characters. The computer name is required, must be 31 characters or less, and can’t contain certain illegal characters.
What are the best practices for using TFS workspaces with Eclipse?
Many users who are new to TFS and/or Eclipse ask for guidance on the best way to configure TFS workspaces and Eclipse workspaces. Some possible configurations lead to problems. The most common actions that lead to problems are manual configuration of working folder mappings and sharing TFS workspaces among multiple Eclipse instances or between Eclipse and Visual Studio.
For the best operation of Teamprise plugin for Eclipse, follow these best practices:
For most users of the Teamprise plugin for Eclipse, TFS workspaces can be mostly ignored as long as the above rules are followed to the letter. Because of this, a future version of Teamprise may include an “automatic TFS workspace” mode that automatically creates a TFS workspace for each Eclipse workspace that needs one.
I’m having a workspace-related problem – how can I reset to a known good state?
Occasionally, problems arise that are related to TFS workspaces or Eclipse workspaces. A common problem is that the TFS workspace becomes out of sync with the Eclipse workspace. For example, suppose that you edit the TFS workspace and manually remove a working folder mapping that was being used by a project in the Eclipse workspace. If this occurs, problems such as inability to connect to TFS from the Teamprise plugin for Eclipse can result.
The safest and easiest way to solve such problems is to reset to a known good state in which the TFS workspace and Eclipse workspace are in sync. To do this, perform the following steps:
Where can I get more information about workspaces?
The following resources provide more information: