Catch-22: Top rookie mistakes in IBM Rational ClearCase


Our experience with beginning ClearCase users over the years has imprinted certain questions and problems indelibly onto our cortices. We thought we would document a few of these to help you condition your own cortex in a similar fashion. We hope this document will be useful both for beginners who ask these questions and administrators who answer them.

I can't see the latest version of

A classic. Typically, either the version containing the desired changes is CHECKEDOUT to a different view, or the user is in a view whose config spec doesn't select the "latest" version the user is looking for. Often the problem is that the term "latest version" is ambiguous. Ask the user whether he means latest in production, QA, in his development sub-team, etc.

What does "Eclipsed" mean?

Officially, an Eclipsed element is obscured by a "view-private" object. A more user-friendly explanation, however, is that a dynamic view isn't able to delete the local copy of a file after the user checked it in. A third-party tool locking the local file and preventing ClearCase from deleting it during check-in usually causes this. Commonly, an Eclipse happens when using the ClearCase and MS Word integration, or with certain IDEs.

The solution for "un-eclipsing" an element is simple. Rename the local copy. After the element is renamed you will observe that the "Eclipsed" icon no longer appears in ClearCase Explorer.

What does "CHECKEDOUT but removed" mean?

(Hint: it's the converse of "Eclipsed.") This problem occurs if an element has been checked out and the checked out object is then deleted using Windows or UNIX/Linux commands (such as delete/rm or rmdir, or their GUI equivalents). Assuming the user wants the element back, the solution to this problem is to un-checkout the file or directory.

I just added a new file to the ProjectX directory. How come no one can see the new file in any of their views?

Another classic. There are several possible resolutions:

Make sure that the user created the element using Add to Source Control from the menu selection (or using the cleartool mkelem command).

Check in the element that was added, making sure the directory where the elements have been added has been checked in.

Make sure other users have a view with a config spec that allows their view(s) to see the new element.

Make sure other users have updated their snapshot views.

Why do I need to use branches? Why can't I just do all my work in the "main" branch?

Certainly, you can work in just the "main" branch. However, working in just one main-line branch limits a project by allowing ONLY checkouts from the baseline. This means that two people can't work on the same file at the same time without interfering with each other when it comes time to deliver their work. Do you really want to take the chance every time you try to deliver a bug fix to your team leader that you'll have to call up another developer and coordinate a bunch of unrelated (and probably incomplete) changes? If you use multiple branches, you can check out and check in to your heart's content and not worry about conflicting changes with another user until it makes sense to.

Why do I have to create a "label type" before I put the label on my element?

(This answer covers all of the metadata types in ClearCase.) Essentially, label types allow you to work easily with labels at either an individual (per-file) or group level. If you didn't have label types, you couldn't easily lock or delete a label; you'd have to lock or delete all the individual labels with the same name on every file they're applied to.

(UNIX) I set my directory to /devvob but I don't see any files or directories in it!

The most common causes of this behavior are: The VOB has not been mounted and/or the view has not been started or set.

The solution? Mount the VOB and/or set the view.

(Windows) I can't find the devvob directory!

The user probably hasn't mounted the VOB. The solution? Mount the VOB from the command line or from the Windows or ClearCase explorer.

I tried to edit the file but the error states that it's a "read-only" file system.

This error occurs when an element has not been checked out. The solution? Just check out the element.

I checked out a file but I accidentally deleted it. Is it gone? How do I get it back?

Well, unfortunately, the changes you made to the file while it was checked out are gone unless you have backup procedures in place that run very frequently and back up view-private files. Otherwise, you can't get the changes you made to the file back. You must treat this as a "Checked out but removed" problem.

Can I version Word documents?

Yes, ClearCase is integrated with MS Word versions 97, 2000, and XP. Activate the integration by clicking the Start button and go to Programs > Rational ClearCase Administration > Integrations > Microsoft Word Integration Configuration. Click on "Yes" to the displayed panes.

How can I see just Final Release Version 1.0.3 that is identified with the label "R1.0.3.FINAL"?

Create or modify a view and set the config spec to:
element * R1.0.3.FINAL. This label will show ONLY elements that have been labeled R1.0.3.FINAL.

How can I work at home when I can't get a ClearCase license?

There are two common ways to do so:

  1. create a snapshot view on your laptop and synchronize with the latest work in the code repositories, or

  2. use ClearCase Web to allow access to the repositories. This method of access provides the user with many of the capabilities that are available as if the user was connected to the development environment. The user can access ClearCase artifacts from any location that is Internet accessible if the administrator allows this.

How can I keep others from changing my work?

It depends on whom you mean by "others." If you mean people outside your primary or supplementary groups in Windows or UNIX/Linux, just remove "other" permissions on the things in ClearCase you want to protect. You use the cleartool protect chmod o-w command to do so.

If those you don't want to make changes are within any of your groups, however, you can't prevent them from making new versions of elements you own via ClearCase permissions. You must lock the elements you don't wish to be changed. To do so, use this command on the elements you wish to protect:

cleartool lock -nusers your-user-id command on the elements you want to protect. This will allow only you (and ClearCase administrators) to do anything to change this element.

What is an Evil Twin?

Let's call him ET. Example: the user removes a file, typically using the command rmname, realizes his mistake and creates a new element with the same name -- we present you your Evil Twin. Versions of the older element still exist in the older versions of the directory. This creates much confusion when working with baselines before and after ET was created.

How to undo ET: If the user realizes the mistake, he should contact the ClearCase Admin to fix the problem. The ClearCase Admin should run a subtractive merge on the file's resident directory. If the user already recreated the element:

  1. rename the element
  2. run the subtractive merge
  3. checkout the recovered file
  4. edit the recovered file according to the changes in the renamed file
  5. last step: delete the renamed file so it does not cause any more problems.

How to prevent ET: There are solutions to the ET problem available from many locations, including here on the Rational Developer Network. These solutions are implemented as pre-operational triggers during a mkelem or add files to source control operation. This is probably the single most important trigger to have in a VOB. (Click here to read more about triggers)

What does "trivial merge" mean? How about "copy merge?"

These two terms are synonymous. Say you work on an element on one branch and merge your work back to another branch. If no one has changed the element on the other branch in the meantime (i.e. since you first began to work on the element on your branch), then there are no conflicts to resolve, and ClearCase can just "copy" your new version of the element back to the other branch. Hence the terms "copy merge" and "trivial merge."

How do I notify my team when a file has been checked in?

The solution is to apply a notification trigger to the VOB that will fire based on rules you define. The rules are implemented in a script fired by the trigger. For more on triggers, click here.

How do I Edit HTML files in ClearCase? If I double-click them it just opens them up in my browser, and there's no right-click option to Edit HTML files like there is in Windows Explorer.

It's very easy to create an "edit" option -- or any other option, for that matter -- within a right-click menu in ClearCase Explorer. Just use the ClearCase Context Menu Editor (available under Rational ClearCase on the Start menu). The whole purpose of this tool is to extend the capabilities in the ClearCase "right-click" menus on elements. Just specify the new menu choice and what it should do (e.g. bring up FrontPage), and deploy this menu to every workstation needing it.

I just revised my directory structure using Windows Explorer, changing the hierarchy and renaming some entries. Why is my ClearCase administrator looking down and sighing?

(This is only possible with snapshot views) If you want to change the structure of directories under ClearCase control, you have to do so through ClearCase. Otherwise, your local structure won't match that in the VOB, and the next update you do of your snapshot view will wreak havoc with your local environment. Perform your moves and renames using the ClearCase GUI or use the cleartool mv command, and ClearCase will assure that these changes are known and tracked.

I can't see many files that were in my snapshot view yesterday. Later I discovered that someone else had changed the directory structure for my team's component. Why didn't anyone tell me that I should have refreshed my view from the top, and that refreshing just part of the view does not give correct results when someone changes the directory structure? Why can't ClearCase figure out that the directory structure has changed and refresh accordingly?

Snapshot views are static windows into the repository. This means that if you want the window to change, then you must Update the View, or portions thereof. If ClearCase automatically updated the entire view every time, users wouldn't have the choice to narrow the load rules to reduce load times. You can choose whether all or part of a snapshot view is updated by altering the view's load rules. It is up to the user to take care and update the Snapshot view appropriately to keep up to date with the changes that occur in a dynamically changing environment.

"Why do I have to use a command line program to add a lot of files under ClearCase control at once? Shouldn't this be part of the user interface?"

Don't want to use the command-line interface for large file migrations? No problem. Here's how to move those files in your existing Windows environment.

  1. In ClearCase Explorer or Windows Explorer, move the files or folders to the VOB directory that will serve as the parent directory.
  2. Select the items to add to source control. Then right-click.
  3. We recommend that you select items farthest from the root of the directory tree: the Add to Source Control command for any given file or directory also adds any parent directories (up to the VOB root directory) that are not already elements.
  4. On the ClearCase shortcut menu, click Add to Source Control.

When an element has been changed in two or more views, and I know which one I want to keep, why can't I just choose the one I want? ClearCase insists on doing a merge.

You can choose the version you want from within the merge tool, either graphically or via the command line.

Downloadable resources


Sign in or register to add and subscribe to comments.

ArticleTitle=Catch-22: Top rookie mistakes in IBM Rational ClearCase