This page last changed on Mar 24, 2011 by dhansen@atlassian.com.
This page contains instructions for how to set up a ClearCase repository in FishEye, a configuration reference and a list of known issues.
If you also have Crucible, you will also be able to run Crucible reviews on code from your ClearCase repository, once configured.
On this page:
Requirements
The instructions on this page require the following:
Applications:
- IBM ClearCase 2003.06.10 or later
- The cleartool command must be installed on the same server as FishEye and must be available in the PATH of the user that is running FishEye.
Permissions:
- The FishEye process must be run as a user that is part of the required groups with access to the ClearCase VOBs. This is because FishEye uses the Cleartool client to access VOBs, and ClearCase uses the user and group information from the operating system to grant or limit access to VOB content.
Setting up a ClearCase Repository
To add a ClearCase repository,
- Open the 'New Repository' dialogue by following the instructions on Adding a Repository.
- Set your ClearCase repository details, as described below. Also see the screenshots below.
|
1. Enter the Basic Repository Details
Field |
Description |
Allowed values |
Repository Type |
Select 'ClearCase'. |
ClearCase |
Name |
Enter a display name. This name will be displayed in the list of FishEye repositories. |
Free text |
Description |
Optionally enter a description for this repository. |
Free text |
2. Enter the ClearCase Settings
Field |
Description |
Allowed values |
View Location |
If 'Auto Create View' is ticked, enter the location of a directory accessible to the FishEye instance where snapshot views can be created.
If 'Auto Create View' is not ticked, enter the location of an existing ClearCase view. This can be either a dynamic or a snapshot view. (Note, this is not the view storage location typically .vws directory). |
A system path |
Auto Create View |
Tick the checkbox, if you want FishEye to create views for each VOB or UCM Project being indexed.
Do not tick the checkbox, if you want FishEye to use an existing view (specified in the 'View Location' field below). |
Yes/No |
UCM |
Choose whether the underlying ClearCase repository uses UCM or Base ClearCase.
The rest of the fields on this screen will change depending on which option you choose (see screenshots below) |
Yes / No |
If you have selected 'UCM' to be 'No' (i.e. you are configuring a Base ClearCase repository) complete the following fields:
Field |
Description |
Allowed values |
Main Branches Only |
Tick this checkbox, if you only want changes made on the main branch or delivered to the main branch to be indexed. Do not tick this checkbox, if you want all changes to be indexed. |
Yes / No |
Index Start Date |
Enter an index start date, if you only want changes that were made after this date to be indexed. Note, files that have not changed since the index start date will not be displayed at all. |
Date (YYYY-MM-DD) |
Block Size |
Enter the block size, i.e. how many change sets FishEye and Crucible will process in one batch.
(This setting only displays if you tick the 'Show advanced settings' checkbox at the bottom of the dialogue.) |
Number |
Command Timeout |
Enter how long you want FishEye and Crucible to wait for ClearTool commands to complete, e.g. "100000". If not set, this will default to "3600000".
(This setting only displays if you tick the 'Show advanced settings' checkbox at the bottom of the dialogue.) |
Number (in milliseconds) |
VOB to Include |
If you only need FishEye to index a single VOB, select the VOB to index. The dropdown list will contain all non-UCM VOBs found in the ClearCase installation. |
Auto-populated |
Include Pattern |
If you need FishEye to index multiple VOBs, use a pattern to specify which VOBs to include. Multiple inclusion patterns can be separated with a comma.
See the Inclusion/Exclusion Settings section for examples of inclusion patterns. |
Free text |
Exclude Pattern |
If you need FishEye to index multiple VOBs, use a pattern to specify which VOBs to exclude. Multiple exclusion patterns can be separated with a comma.
See the Inclusion/Exclusion Settings section for examples of exclusion patterns. |
Free text |
Branches to Include |
Enter the list of the branches to include in indexing. An empty list will cause all branches to be indexed. |
Table |
Branches to Exclude |
Enter the list of the branches to exclude from indexing. |
Free text |
If you have selected 'UCM' to be 'Yes' (i.e. you are configuring a UCM ClearCase repository) complete the following fields:
Field |
Description |
Allowed values |
Integration Streams Only |
Choose whether FishEye and Crucible should index changes made on development and integration streams or only integration streams. We recommend that users choose 'Yes' for this option. |
Yes / No |
Include Integration Activities |
Choose whether to include integration activities, i.e. when enabled, rebase and deliver activities will also be indexed. |
Yes / No |
Index Start Date |
Enter an index start date, if you only want changes that were made after this date to be indexed. Note, files that have not changed since the index start date will not be displayed at all. |
Date (YYYY-MM-DD) |
Block Size |
Enter the block size, i.e. how many change sets FishEye and Crucible will process in one batch.
(This setting only displays if you tick the 'Show advanced settings' checkbox at the bottom of the dialogue.) |
Number |
Command Timeout |
Enter how long you want FishEye and Crucible to wait for ClearTool commands to complete, e.g. "100000". If not set, this will default to "3600000".
(This setting only displays if you tick the 'Show advanced settings' checkbox at the bottom of the dialogue.) |
Number (in milliseconds) |
Project To Include |
A drop down list displaying all the UCM Projects found in the ClearCase installation. If users only require that FishEye index a single UCM Project, they should select the Project to index from this drop down list. If 'Auto Create View' is set to 'False' (i.e. using an existing view), you must select a single project not 'All', as a view can only be used for a single UCM project. |
Auto populated |
Project Include Pattern |
If you need FishEye to index multiple UCM Projects, use a pattern to specify which UCM Projects to include. Multiple inclusion patterns can be separated with a comma. See the Inclusion/Exclusion Settings section for examples of inclusion patterns. |
Free text |
Project Exclude Pattern |
If you need FishEye to index multiple UCM Projects, use a pattern to specify which UCM Projects to exclude. Multiple exclusion patterns can be separated with a comma. See the Inclusion/Exclusion Settings section for examples of exclusion patterns. |
Free text |
Streams to Include |
Enter the list of the UCM streams to include in indexing. An empty list will cause all streams to be indexed. |
Free text |
Streams to Exclude |
Enter the list of the UCM streams to exclude from indexing. |
Free text |
3. Enter the Final Settings
Field |
Description |
Allowed values |
Store Diff Info |
Choose whether to enable the Store Diff Info setting. See Store Diff Info for more information on this setting. |
Yes / No |
Enable Repository After Adding |
Choose whether the repository will be accessible in FishEye immediately. |
Yes / No |
Screenshots: Adding a ClearCase Repository (click to view gallery)
|
|
|
|
Step 1
|
Step 2a (Base)
|
Step 2b (UCM)
|
Step 3
|
|
Notes
Inclusion/Exclusion Settings
|
The following points provide guidelines for the settings which may need to be applied in order to restrict the number of ClearCase Projects/VOBs indexed by FishEye:
- If you want all the VOBs/UCM Projects within your environment to be indexed, then you don't need to add any additional information on the Edit Repository screen. This is the default behaviour.
- If you want several VOBs/UCM Projects to be included (but not all), then you should include appropriate details in the VOB Includes/Excludes fields
- If you only wish for a single VOB/UCM Project to be indexed, then you should select the specific VOB/UCM Project from the 'VOB to Include' or 'UCM Project to Include' drop down list. This will force FishEye to only index the selected VOB/UCM Project.
When using the Includes/Excludes fields, you can enter one or more patterns, separated by a comma (note, you cannot use spaces). A pattern can be either a regular expression or a plain string. Matching is done as follows:
- A plain string pattern is considered to match a VOB or UCM Project if the string is part of the VOB/UCM Project (e.g. myvob matches vob:/vobs/myvob and vob:/vobs/myvob2)
- A regular expression is considered to match a VOB or UCM Project if it is the regular expression matches the VOB/UCM Project string (e.g. project:.*_Release.* matches project:Product1_Release2.1@/my_pvob)
For Base ClearCase configurations, the patterns are matched against the VOB name as listed in the select box (e.g. vob:/vobs/yourvob):
VOB Include/Exclude Pattern |
Description |
/vobs/myvob1,/vobs/myvob2 |
matches /vobs/myvob1 and /vobs/myvob2, but also /vobs/myvob12 |
vob:/vobs/.*vob |
regexp pattern that matches /vobs/myvob, /vobs/yourvob, but not /vobs/myvob2 |
vob:/vobs/.*vob,/vobs/myvob1 |
combination of a regexp pattern and a simple VOB name. |
For UCM ClearCase configurations, the patterns are matched against the full UCM Project as listed in the select box (e.g. project:MyUCMProject@/my_pvob):
UCM Project Include/Exclude Pattern |
Description |
MyProduct1,MyProduct2 |
matches all UCM projects whose name contains MyProduct1 or MyProduct2 (e.g. MyProduct12_Rel3.1) |
project:MyProduct_Rel\d+.* |
regexp pattern that matches MyProduct_Rel1, MyProduct_Rel2, but not MyProduct_CoolNewFeature |
.@/my_pvob,.@/my_otherpvob |
regexp patterns that match all UCM projects in the /my_pvob and /my_otherpvob PVOBs. |
|
View Creation
|
As part of the repository scanning logic, FishEye will create a view for each Project (for ClearCase UCM environments) or VOB (for Base ClearCase) using the locations defined in the 'View Location' and 'View Storage Location' fields. This is required in order for the underlying 'cleartool' commands to be executed in the correct context. Please note that FishEye will not perform updates on these views - it is intended that these views will remain unpopulated. |
Indexing Logic
|
It may be helpful to understand how FishEye's ClearCase support carries out indexing. Please see the following sections:
UCM ClearCase Indexing:
The ClearCase support will attempt to index all the available content within a ClearCase environment. The logic works as follows (ClearCase specific terms are underlined see definitions):
- All PVOBs that are available are identified.
- For each PVOB, find all the Projects contained within the PVOB.
- For each Project, find all the Streams associated with the Project.
- For each Stream, find all the Activities that have been delivered to the project.
- Find the Versions that were included in each Activity and index the Version information.
- Any Labels attached to Versions are also indexed.
PVOB stands for Project Versioned Object Base.
Base ClearCase Indexing:
The logic for the Base ClearCase support is,
All non-UCM VOBs that are available are identified.
- For each VOB, find all the Branches that contain versions.
- For each Branch, find the check-ins and index the version information.
- Any Labels attached to Versions are also indexed.
|
Allocating Time for Repository Scanning
|
The initial scan of a repository is a time and resource intensive operation, more so if the ClearCase repository being indexed is large (both in terms of the number of ClearCase projects and the number of change sets included in each project). In the Atlassian test environment (running in a virtual machine), each commit included in a change set would take approximately one second to complete (the time taken in a non-VM environment seems to be slightly faster at approx 700ms). You can use these numbers to estimate the time it will take to scan your repository; it could take many hours or possible days to complete. |
Changelog
Changes included in 2.1.3
|
Config.xml schema changes:
The structure of the underlying schema for the ClearCase configuration config.xml file has changed. The effect of this is that for repositories created prior to version 2.1.3, the VOB/UCM Project Inclusion rules won't appear in the Administration UI. However, the previously entered values for these fields will still be used as part of the repository scanning logic.
In order for these fields to be displayed in the Administration UI, the values for these fields should be re-entered.
Interactive invocation of cleartool commands:
As a performance improvement measure, a number of the cleartool commands executed by FishEye as part of the repository scanning logic are now executed in 'interactive' mode. That is, a cleartool process (one per repository) is kept open for the duration of the indexing process.
The execution of commands in interactive mode can be disabled by adding a 'disableInteractiveProcess' attribute to the specific ClearCase repository defined in the config.xml file.
Performance Improvements:
Subsequent indexing operations for Base ClearCase repositories will take the last indexed date into account, so the 'cleartool lshistory' output will only include those changes that have not already been indexed. |
Changes included in 2.1.2
|
In the first release, the include/exclude rules for VOBs and Projects were handled by the 'Include/Exclude' rules item on the administration page. Based on feedback received during initial version testing, this has been updated to provide additional flexibility:
- The VOBs which are indexed can be controlled via the 'VOB to Include' and 'VOB Include/Exclude Patterns' fields.
- Similarly, the UCM Projects which are indexed can be controlled via the 'UCM Project to Include' and 'UCM Project Include/Exclude Patterns' fields.
- The Include/Exclude rules on the Administration page now apply to files/directories that are indexed within a ClearCase VOB/Project. The values entered into these fields perform the matching logic as defined on the Allow (Process) page
|
Known Issues
There are a number of known issues with ClearCase support in FishEye. These are listed below.
XML files cannot be viewed as 'Annotated' source
|
Currently XML files cannot be viewed as 'Annotated' source. By default, ClearCase using a specific type manager to store XML files. This type manager does not support the 'cleartool annotate' command, which is used by the logic in FishEye that displays the Annotated source.
Further to this, by default ClearCase treats any files not defined in the 'default.magic' file as 'compressed' (for instance, property files are not included in the default.magic file). Only text-based type managers can be annotated (and hence, can be displayed via the 'Annotated Source' link). The type manager can be updated by performing the following steps:
- Update the default.magic file to include appropriate rules that specify the type manager to use for files of a given naming convention (this will take effect for newly created elements)
- Modify the type manager for existing elements through the 'cleartool chtype' command.
Further information on the ClearCase type manager is available on the following pages:
|
Cleartool output limited to 64K of data
|
There is a known bug with earlier versions of ClearCase that limit the Cleartool output to 64K of data. This may affect projects that contain a large amount of changes included in a changeset. This bug can be fixed by upgrading ClearCase — see this page for more information. |
Feedback and Support
Please raise a support ticket to seek assistance with FishEye ClearCase support.
|