Mapping Preferences

Window > Preferences > Team > StarTeam > Folder > Mapping

Note: You can set folder mappings in the client using the Mapping options in the Preferences dialog box or at the project-level using the Properties menu found in the Eclipse Explorers on shared projects.

The Mapping preference settings allow you to map repository folders to your Eclipse workspace folders. These preferences enable you to change the naming of local folders taken from either the human-readable names of StarTeam folders or their path fragments. These options correspond to using default or alternate working folders in the Cross-Platform Client.

Note: Most users should use the default setting. It is not advisable to change the folder mappings on-the-fly. You should keep your folder mappings consistent for the duration of the workspace.

You can customize the following mapping options at the default and project-specific levels:

Map name (and replace non-path characters by '-'): The default setting.
Map path fragment: The setting used to indicate alternate folder names.

You do not have to be concerned with Mapping preferences for project, view, or root folder names. These names are associated with internal identifiers (IDs), so there is no need to use any type of Mapping preferences. You can name your local project whatever you like. Mapping does not apply at all in this case, and the default name suggested for the local project is the root folder name of the view; however, since the project, view, and folder IDs are used for sharing, the local project name can be changed at your own discretion.

However, the client handles local folder names differently. While the relationship between local folders and remote (server-side) folders is established by an ID, on an initial folder mapping or a local folder creation and naming, the Mapping Preferences apply for how the client identifies folders that have not yet been shared and finds suitable remote folders for them.

Path fragments are server-side only and do not change any property for the client. However, if you choose in the client to use path fragments for the workspace folder naming, you may need to refresh the latter to be aware of the remote changes. A local, automatic adjustment does not exist if you change the path fragment so drastically that the local folder is no longer named accordingly. If this happens, the local folder will loose its relationship to its remote peer despite the folder ID it remembers and show up as a local addition in the client.

Note:

By default, StarTeam uses remote (server-side) folder names for the local workspace folder names. The standard mapping setting is not to allow mapping at all. However, you can change the Mapping options to use the folder path fragment. Relative paths (../../x/y/z) are not accepted. Alternatively, the mapping can default to the last segment of the path fragment.
You can check-in the Eclipse <project>/.settings/com.microfocus.team.starteam.provider.prefs file to share the same folder mapping settings for that project across teams. To provide general mapping coherence, you can export and share the preferences on a file server for importing by team members.

Map name (and replace non-path characters by '-')

The default setting. Maps to the default setting for StarTeam Server-side (remote) folders. Most users will use this as their default setting. This means that you are using the default folder name provided by the Server to name your local folders.

Map working folder

Use this option to set alternate working folders. You can choose from the following options to handle an absolute or relative working folder path:

Default to last segment - Use this setting to keep the last segment of the path. This is helpful for users that redirect folders to other locations without actually changing the last segment of the working folder path from the initial short working folder. For example, you may want to use this option for folders that you never perform a check-in on, such as a folder that you locally name as, plugins[DO NOT CHECK IN].
Report error - Does not allow remote folders with complex working folder paths to be mapped. This option keeps you from checking out folders that are pointing to other locations other than the default setting on the Server.

Configure project specific settings

You can overload preferences on a per-project basis. This link opens the Project Specific Configuration dialog box where you can select a project and configure mapping preferences specifically for it.

Overloaded preference settings are stored within a project in the path ".settings/com.microfocus.team.starteam.provider.prefs". You can check them in and share them across teams to enforce the same folder mapping for every team member.

Folder Mapping Examples

Imagine a StarTeam project that has the following folder structure (folder name in quotes, working folders in parenthesis):

"<My Project>" (C:\prj)
    "CRs/Tasks/Requirements" (process)
    "Documentation" (../html/docs)
    "Source" (S:\src\java)

The three mapping methods create the following workspace structures:

Map name (and replace non-path characters by '_') ... "comments in quotes"

        _My Project_ ... "the '<' and '>' characters in the root folder name get replaced by '_' to comply with eclipse resource naming rules"
            CRs_Tasks_Requirements ... "the '/' characters in this folder name get replaced by '_' to comply with platform file and folder naming rules"
            Documentation ... "no conversion needed for this folder name"
            Source ... "no conversion needed for this folder name"

Map working folder ...
    ... If absolute or relative working folder is set ...

... Default to last segment

        prj ... "the last segment of the absolute path in the view '<My Project>' working folder 'C:\prj' is used"
            docs ... "the last segment of the relative path in the 'Documentation' folder's working folder '../html/docs' is used"
            java ... "the last segment of the absolute path on another drive in the 'Source' folder's working folder 'S:\src\java' is used"
            process ... "the working folder of folder 'CRs/Tasks/Requirements' can be taken unchanged"

... Report error ()

            An exception would be thrown at sharing, indicating the first absolute path used for the view's working folder as non-mappable.

The Cross-Platform Client allows folders with an empty working folder property. Such folders will not map into Eclipse workspaces when using working folder mapping, and a thrown exception prevents projects with such folder structures from synchronizing properly.

Note: The workspace project name does not need to be the same as the folder name and working folder path. The sharing parameters are ID-based to allow both remote and local renaming without losing the sharing. Nonetheless, wizards that check out repository folders as workspace projects observe the mapping preferences, and choose the suggested project name based on the general mapping preferences. If mapping is not configured to use folder names, the last segment of the working folder is suggested for project naming.