ClearCase Cheat Sheet

Not all users of ClearCase use the Unified Change Management (UCM) process.  In fact, base ClearCase is an excellent choice for projects that don’t require the process enforcement and activity management that UCM provides but who still want the security, scalability, auditability, traceability and stability inherent in ClearCase.

​Base ClearCase is easy to use with just a few common operations that allow developers to quickly and easily do the things they need to do.  The following is a “cheat sheet” for developers that provides a short dictionary of those few common command-line operations that allow developers to make use of the power of the ClearCase software configuration management system.  Most of these command-line operations have analogues in the ClearCase GUI interfaces, but typically, the command line form of the operation has greater flexibility.

Base ClearCase Cheat-Sheet
Views
How many Views do I need?
Generally, one per discrete task is a good idea, though this is not a requirement.  Views should be regarded as “cheap” entities that are easily created and destroyed.  Create one for each task you need to do and when that task is done, delete the view.

How to Create a View
Use the following command:
 
cleartool mkview -tag atag  storage-location
 
Where “atag” is the view-tag (the “name” of the view which should be a mnemonic name that you can easily remember) and storage-location is the location of a place on a disk where the view can store information.

How to Delete a View
You should not use the UNIX “rm” command or the NT file manager to remove views.  Instead, use the following command:
 
cleartool rmview -tag atag
 
Where “atag” is the view-tag of the view you want to remove.

Modifying Files
Checkout
To modify an element you need to check it out.  Do this with the following command:
 
cleartool co anelement
 
where “anelement” is the name of the file or directory you want to check out.

Checkin
Once you are happy with the changes you have made to a checked-out element, you can check it in with the following command:
 
cleartool ci anelement
 
where “anelement” is the name of the file or directory you want to check in.  Once you check-in an element, the changes you made to that element are usable by everyone on your project.

Uncheckout
If you want to cancel a checkout, you can do so with the following command:
 
cleartool unco anelement
 
where “anelement” is the name of the file or directory you want to check in.

Creating New Files
Creation
To create a new file, you can use whatever editor or command you would normally use to create the file.  The new file will be a view-private entity until you take the next step to put it under ClearCase control.

Putting a File Under Version Control
To put a file under ClearCase control you must first check-out the directory that will be containing the file, issue the command to tell ClearCase to put the file under version control, and then check-in the directory containing the new file.  Here are commands to perform these steps:
 
cleartool co thedirectory
cleartool mkelem thefile
cleartool ci thedirectory
 
After this sequence is performed, the file “thefile” is still checked-out and can be modified further before you check it in.

Deleting Elements
To remove an element you should use the “cleartool rmname” command.  This command removes the name of the specified element from the the directory in which it is contained.  Similar to placing an element under ClearCase control, you must first check-out the directory containing the element to be removed, do the “cleartool rmname” of the element, and then check-in the new version of the directory.  Here is an example:
 
cleartool co thedirectory
cleartool rmname anelement
cleartool ci thedirectory
 
After this sequence, “anelement” is no longer listed in subsequent versions of “thedirectory”.  It is, however, still listed in previous versions of the directory.  If, at a later date you want to re-add “anelement” to a new version of “thedirectory” (or any other directory), you can do so easily.

Renaming Elements
Renaming an element is similar to deleting it.  First you check-out the old directory containing the element, and you also check-out the new directory to which the element is to be moved.  Then you use the “cleartool mv” command to perform the move operation.  Be sure to check-in the old and new directories when you are done.
 
cleartool co .
cleartool co newdirectory
cleartool mv anelement newdirectory
cleartool ci .
cleartool ci newdirectory
 
Renaming an element is also accomplished using the “cleartool mv” command except the old directory and the new  directory are the same.
 
cleartool co .
cleartool mv anelement anewname
cleartool ci .
 
In subsequent versions of the directory, the name “anelement” will not appear, having been replaced by “anewname” but the name “anelement” will still appear in prior versions of the directory.  Both the names “anewname” and “anelement” will still refer to the same element; only the name associated with the element in the directory will have changed.

Getting Information
About Views
What View am I in?
At any given time you can tell what view you are in by issuing the following command:
 
cleartool pwv
 
“pwv” means “print working view” in the tradition of the UNIX command “pwd” for “print working directory”
 
What is my “config-spec”?
Recall that a configuration specification (config-spec) is the set of rules that tells ClearCase what configuration of elements you want to work with.  You can see that set of rules by issuing the following command:
 
            cleartool  catcs
 
How do I change my config-spec?
You can edit your config-spec by issuing the following command:
 
            cleartool edcs
 
Your favorite editor , as specified by the environment variable WINEDITOR (first choice), VISUAL (second choice), or EDITOR (third choice) will be invoked for the editing operation.  If none of these environment variables is set then vi will be invoked for the editing operation on UNIX systems and Notepad will be invoked for the editing operation on Windows systems.

About Files/Directories
What is checked-out and to whom?
If you want to see who has what checked-out, you can use the “cleartool lsco” command.  This command has a number of possible arguments to use depending on the specific information you want.  Here are some common ones:
 
cleartool lsco
Lists all checkouts of elements in the current directory.
 
cleartool lsco anelement
List checkout information about the element “anelement”.
 
cleartool lsco -recurse
Lists all checkouts of elements in the current directory and below.
 
cleartool lsco -cview
Lists checkouts of elements in the current directory that are checked-out to the current view.
 
cleartool lsco -cview -recurse
Lists checkouts of elements in the current directory and below that are checked-out to the current view.
 
cleartool lsco -me
Lists checkouts of elements in the current directory that the current user has checked-out.
 
cleartool lsco -user fred
Lists checkouts of elements in the current directory that the the user with  login id “fred” has checked-out.
 
Please refer to the ClearCase Reference Manual for more detailed information about the “cleartool lsco” command.

What is the change history of this file/directory?
If you want to see the change history associated with a particular element, you can use the “cleartool lsh” command.
 
cleartool lsh anelement
Where “anelement” is the name of  an element under ClearCase control

What versions of what files/directories am I looking at?
To see exactly what versions of elements are being projected to you by your view and why, you can use the “cleartool ls” command.
 
cleartool ls
 
What are the differences between this version of a file/directory and a different version?
To view the differences between the version of an element visible in your view and another version of the element you can use the “cleartool diff” command.
 
cleartool diff –g -pred anelement
Graphically presents the differences between the version of “anelement” selected  by your view and it’s immediate predecessor version.
 
cleartool diff -g anelement anelement@@/main/5
Grapically presents the differences between the version of “anelement” selected by your view and version 5 on the main branch of “anelement”
 
You can also use this command without the “-g” option to present the difference information to you textually rather than grapically.

See the “cleartool diff” entry in the ClearCase Reference Manual for more detailed information on these commands.

What does the version tree look like for this file/directory?
To view a graphical representation of the version tree associated with an element you can use the “xlsvtree” command.
 
cleartool lsvtree –g anelement
 
You can view a textual representation of the version tree associated with an element with the “cleartool lsvtree” command.
 
cleartool lsvtree anelement
 
I want more information about this element
You can get more detailed information about a particular element with the “cleartool describe” command.
 
cleartool describe anelement
Lists information about “anelement” such as the version selected by your view, who created it and when, the comment associated with the version, the element type and the predecessor version.
 
These few commands and concepts allow developers interact with and make effective use of ClearCase.  There are many other operations possible with ClearCase that allow developers to share code safely as well as to analyze an organization’s software development processes.  I encourage you to review the ClearCase command reference manual to gain an understanding of the depth and power available in ClearCase, whether you use UCM or not.

Tom Milligan
Senior Area Sales Director
Software Change and Configuration Management
Connect with me on LinkedIn