ClearCase lingo demystified

Print Version

General Considerations on ClearCase terminology

ClearCase is a tool for controlling versions of software and document files ( There are many such tools, some open source and free, but ClearCase has a special advantage of using a proprietary file system for storage and maintenance of files and associated meta data. On the surface, when you work in ClearCase, your Unix commands and applications work the same as if you worked on the native file system. Actually almost the same... Some applications that use kernel low level file operations may have problems, similar to the problems of working on the remote file systems, like NFS. A practical example comes from Apache Web Server. When you are serving documents/images from the directory under ClearCase view you need to set the EnableSendFile to Off to disable an efficient but raw file access. However, situations like that are very rare, and traditional libc based file access works fine.

This write-up assumes Base ClearCase on Unix/Linux. I do not discuss anything about other OSes that ClearCase runs on. This is written for people who use ClearCase now, but they do not know what they are doing and they are tired of this feeling. It is not a tutorial on ClearCase. If you know what you are doing, read no more and do not waste time... I will also not deal here with UCM (Unified Change Management), the derived objects (i.e., using the UNIX-type make in the ClearCase), with distributed ClearCase installations (i.e., when files reside on different machines that may or may not be on-line all the time) and with snapshot views. This will not teach you much if you do not already use the ClearCase. There are books, read them to get the knowledge. My goal here is to explain the basic terms used in ClearCase that represent simple concepts but are so overblown with a mystique of ClearCase (which is: the greatest thing since sliced bread, obviously) that they prevent a rational person to understand what is happening.

Note, I really dislike ClearCase since it wasted a lot of my time. The terminology is not intuitive and it is confusing. They tried to create newspeak for secretaries or lawyers who will keep versions of their memos under ClearCase. They forgot that ClearCase is primarily used by programmers, forced to use it by corporate policies. These folks are usually familiar with object oriented technologies and had to write a few topology routines to get a passing grade for Computer Science 101. I am not sure what they were thinking creating this lingo. Probably they wanted to convince us that they created something so new that no other mortal had ever come close to thinking about -- a version control. The terms like Mastership of the label type (i.e., who owns and can change the label) just make you wonder... Since ClearCase also runs on Windoz, maybe they wanted to use the successful marketing policies... You get stuck...

Set PATH to ClearCase commands

Before you can use ClearCase, you need to set your PATH environment variable to contain the directories where the ClearCase commands and macros reside. This is installation dependent, though a default directory where the ClearCase commands reside is usually /usr/atria/bin. So you should have something like:

export PATH

in your ~/.bashrc (if you are using bash shell) or in your ~/bin/kshinit (if you are Korn shell aficionado) or something like:

set path = ( /usr/atria/bin $path )

in your ~/.cshrc file if you are too lazy to learn a decent shell and you are still using the C shell.

There may be more directories to place in the PATH that contain additional utilities, scripts or macros. Some of them may be actually placed under the /vobs directory to make them available only when you are in the ClearCase view. Your ClearCase administrator should tell you all about it, and also add you to the ClearCase Unix group(s) to allow you to access files. You will also be most likely asked to put some aliases into your UNIX rc files, like:

alias ct="cleartool"

to type something like:   ct command   rather than   cleartool command  .

Reading the ClearCase man pages (i.e., using ct man command_name command) is actually waste of time if you do not know the confusing terminology. To understand ClearCase better you may refer to some links that I found quite useful:,, and ClearCase%20VOBs%20how%20do%20I.htm#_Scripts_and_utilities. I could list here a few pointers to the the IBM site, and there are some very useful documents there, but they use this lingo of theirs and before you go there, you need to know what they mean. But stay with me for a while before you start clicking and googling...

You will need to make at least two iterations when reading this brain dump, since the terms are so interdependent that I could not find a way to do it the A -> B -> C... way. Sorry... I will use some typical abbreviations below. For example, the ClearCase commands are usually executed by typing: cleartool some_command. I usually abbreviate it as ct some_command since I have the alias ct="cleartool" in my .bashrc to save on typing. Most users of ClearCase have the same alias set for them.

What is Type (what is hype?)

The popular task in ClearCase is first to make a type of something and then to use the something. Luckily some basic element types are already pre-made in ClearCase. But other objects require you to make types first. For example, you first create a label type and then assign the label to the element version. I think that what the creators of the newspeak did here is renamed terms from object oriented design. The type of something is a Class, i.e., the prescription of how to construct something, while something is an Object constructed from the Class. In this context, the label type will be the Class describing how to construct the label, while label is an object created from the Class label type. Similarly a branch type is a Class, that is a construction blueprint for a branch, while branch is just an instance of the given branch type (i.e., an Object). Of course, IMHO, all this is pure hype and even using Object Oriented Programming terms is not needed. A label is just a string that you associate with the element version and a branch is a directory (or a link to it) on the VOB where you put subsequent element versions. And the element is just a file or directory. They just created Abstract Universe and a new New Paradigm out of the Scrapbook. The learning curve is steep for no good reason. There is a nice write-up on the types in from where I borrowed the table below and replaced English with my own rendition of it. Basically, for most types you have a mk*type command and a corresponding command that attaches it to some other object:

Make Type
mklbtype mklabel Labels are used to mark a particular version of the element (e.g., file or directory). The most common use for them is to mark a set of particular versions of files and directories that represent a snapshot of a project at some milestone (e.g., a release). Since you are not allowed to assign the same label to two different versions of the same element, labels ensure that creation of new versions of elements in the future does not affect the set of versions marked with a label.

mkattype mkattr Attributes are the name/value pairs. The value can be of different types (e.g., an integer, a string of characters or a boolean value TRUE/FALSE). When you create an attribute type with a mkattype command you need to specify what the values can be. The attributes are very flexible and you can attach them to essentially any object on the VOB, i.e., to an element, to a particular element version, to a branch, etc. You can use them to add some notes or assign some property to the VOB object. You can use the ClearCase ct find ... command and find the elements that have certain attribute values. To tell you the truth, I never used attributes directly.

mkhltype mkhlink Hyperlinks connect a VOB object to another object. Obviously the two objects have to be of the same kind before they can be hyperlinked. The merge arrow is an example of the hyperlink of type Merge that comes predefined with ClearCase. The hyperlinks are logical associations. For example, you can link an element version to a file that describes what has been done.

mkeltype mkelem or
The element type represents a type of file that is created. ClearCase comes with some eltypes predefined, like text_file or directory. The element type is usually assigned to the element automatically based on the magic file that associates extensions of files with the type.

mkbrtype mkbranch The branch is a VOB object that collects consecutive versions of the element. The main branch is predefined in ClearCase. However, if you want to create a new sub-branch, you need to first create it with the mkbrtype command. This is done usually when you create a view which will be placing new element versions on a specific branch according to the rules in the config spec file. Then the config spec file instructs the ClearCase to use mkbranch command to assign the branch to a version of an element. Now you see what I am talking about... The lingo... This is double Dutch (sorry folks from The Netherlands... I did not come up with this on my own...).

Basic Terms

I think that before you do anything with ClearCase you have to know exactly what certain terms mean. This may help you to read the man pages where these terms are used in a more or less inconsistent way. I try to explain in plain language some of terms below:

ClearCase commands and scripts

This would probably be a good place to list popular ClearCase commands. I will not do it, since the thick book would have to follow. One thing to be on alert is that the ClearCase commands are often the same as UNIX commands and many command line options are identical. For example:

% ct setview jkl_koolapp_2.4.3  # set your view. You are still under UNIX shell
% cd /vobs/koolapp              # use UNIX 'cd' to go to your project directory
% ls -l                         # regular UNIX directory listing command
% ct ls -l                      # ClearCase directory listing command

Moreover, when you are in the view you can enter a ClearCase shell and you will only be able to use the ClearCase commands at this stage. In the example below the % denotes the UNIX shell prompt, while cleartool> is the ClearCase shell prompt:

% ct pwv -short                        # which view is selected ?
** NONE **
% ct                                   # switching to ClearCase shell
cleartool> setview jkl_koolapp_2.4.3   # set your view under ClearCase
cleartool> cd /vobs/koolapp            # this is ClearCase 'cd' not Unix 'cd'
cleartool> ls -l                       # this is ClearCase 'ls' not Unix 'ls'
  #  ... ClearCase style directory listing
cleartool> exit                        # back to UNIX with no view selected

Note, in the example above the ct is an alias for cleartool. I personally never switch to ClearCase shell since my fingers would get confused. But some people do switch between UNIX and ClearCase shells and like it. For example, when you use a GUI version of ClearCase (xclearcase) you are automatically in the ClearCase shell, but you can also run a regular shell commands in a window that pops when you click a button.

There are two basic modes to run ClearCase: command line and graphical. Examples above all used the command line since this is how I prefer to use ClearCase (I am an old man). But young folks may like the graphical GUI of ClearCase. Note, that most often, you work on your desktop computer and develop the software on some remote host, e.g., by logging to it via rsh or ssh. If you have X-Window server on your desktop, you need to let the remote host know where to display the widgets. Most often you just need to set the DISPLAY environment variable on the remote host with your desktop computer IP address and the display.screen number information. Assuming that the IP address of your desktop computer is: and your display.screen numbers are the default (i.e., 0.0) you would type something like this in your xterm where you are logged in to the remote host:

export DISPLAY

On the local desktop host, you will need to allow the remote host to access your X-Window display. You need to know the name or IP address of the remote computer. Assuming that your remote host IP address is: you would run something like this on your local desktop computer:

xhost +

or just authorize the remote access when you are prompted for it on first attempt. To open ClearCase GUI, you would just type:

xclearcase &

in the xterm where you are logged in to remote computer. You can also run some commands of ClearCase with the -graphical command line option. For example, to run the ClearCase diff utility in a graphical mode, you would type:

ct diff -graphical file1.txt file2.txt &

that will display the files side by side and highlight differences.

I signaled some basic commands as examples above. You can get the list of individual commands with a ct man command. The page is quite deficient since it lists the commands but does not provide one-line explanations for the most popular commands. However, there is a nice Web page: that provides examples of popular actions with succinct comments what they do. You can easily search it for keywords with the browser's find facility under browser's Edit menu.
I would like, however, to explicitly address the issue of removing elements. My approach is (and I follow the steps of those who really know the ClearCase): not to remove. There is a better way not to carry the unnecessary pieces of software or files or even directories to new views or releases. How? Just do not list them in the directory elements, i.e., remove references to these things from the directories where they reside. They will still be on the VOB under the version of the directory where they were last modified (i.e., in the old view), but they will not be referenced in the new versions of their parent directory (i.e., not seen in the new views). Since you will not normally see them, you will not be able to check them out from now on. However, after you did it, you need to merge your directory element changes to the main branch. This way you will not break any relations between elements and their versions and yet you can get to the obsolete element via a ClearCase @@ path, if you ever needed. Say, you decided that the element: is no longer needed and even harmful and misleading for the new release, since it was superseded by the new element. Assuming that the element resides under /vobs/koolapp/conf directory and you are currently in the jkl_koolapp_2.4.5 view (your view name is the same as the name of your development branch) do the following:

cd /vobs/koolapp/conf              # go to the directory with the element
ct checkin            # element has to be checked in
ct checkout .                      # directory has to be checked out
ct rmname             # remove element entry in the directory
ct checkin .                       # check in the directory were element was

# -- the following can be easier done via GUI
# -- e.g.,  with xclearcase or merge -graphical
# -- or in-house "guru" provided merging script,
# -- merge the LATEST version of . (current dir) in your branch to the main
# -- branch. The .@@/main/CHECKEDOUT is the target contributor while
# -- .@@/main/jkl_koolapp_2.4.5/LATEST is the "other" contributor

ct checkout .@@/main/LATEST        # check out the LATEST version of . on main
ct merge -to .@@/main/CHECKEDOUT  .@@/main/jkl_koolapp_2.4.5/LATEST
ct checkin .@@/main/CHECKEDOUT     # checkin the version of . on main branch

# Check things out if stuff worked...

ls -l .@@/main/
  drwxrwxr-x   2 jkl    ccusrs         40 Jan 21  2007 5
  drwxrwxr-x   2 jkl    ccusrs         73 Jul 10 13:21 6
  drwxrwxr-x   2 jkl    ccusrs         73 Jul 10 13:21 LATEST
ls -l .@@/main/LATEST                      # the file is gone
ls -l .@@/main/6                           # the file is gone
ls -l .@@/main/5                           # the file is there

ls -l .@@/main/jkl_koolapp_2.4.5
  drwxrwxr-x   2 jkl    ccusrs        775 Jul 10 13:19 0
  drwxrwxr-x   2 jkl    ccusrs        696 Jul 10 13:21 1
  drwxrwxr-x   2 jkl    ccusrs        696 Jul 10 13:21 LATEST

ls -l .@@/main/jkl_koolapp_2.4.5/LATEST    # the file is gone
ls -l .@@/main/jkl_koolapp_2.4.5/1         # the file is gone
ls -l .@@/main/jkl_koolapp_2.4.5/0         # the file is there
ct lshistory | more
  # you will see a record of your deeds here...

Of course, the actual merge would be easier done if you used the xclearcase GUI or ran a customized merging script provided by your ClearCase guru/admin. But I wanted to show the mechanics of it and make you wonder what is going on. You can restore the element that was removed from the directory. Check the:

If you have a good ClearCase admin, you will most likely have a number of helper scripts that automatize creation of views, config spec rules and merging, labeling, copying elements from views, etc. These are usually perl or shell scripts that use a UNIX/ClearCase find command(s) and/or UNIX grep/sed/awk commands and process config spec files and elements in your view. These scripts are very dependent on the location of your VOB mount points, your project names, labeling policies and policies related to testing and releases. There are usually not that complicated to write, but there is no one size fits all. If you do not have these things written, have a meeting, establish the rules for development procedures, and have these scripts written and produce document like this: but add your scripts description and examples. Check the Brad Appleton page:, his ClearCase page: and his zipped PowerPoint slides: This is a condition to make ClearCase a workable and efficient tool for those who are not experts in ClearCase use. It will also protect you from disasters (Mom... Woops... I deleted all the latest versions...) and it will make the development process easier to track and will improve collaboration between team members. Unfortunately, there are only few examples of scripts on the Web, but check:,, and

Another way to improve productivity with ClearCase is to create a handful of UNIX aliases for popular operations. Some aliases that I have in my .bashrc file follow:

alias ct="cleartool"                    # cleartool -> ct
alias cv="cleartool pwv -short"         # tells me which view I am in
alias ctco="cleartool checkout -nc"     # checks out a file or dir w/o comment
alias ctci="cleartool checkin -nc"      # checks in a file or dir w/o comment
alias ctchmod="cleartool protect -chmod "  # change CC default protection

When you try to write your own ClearCase scripts, make sure that you pay attention to the UNIX exec varieties. The SHLVL environment variable or a ps shell utility that you will run in another xterm, may help. There are also UNIX commands like ptree or pstree that can help you to traverse UNIX process tree visually. This is important, since some ClearCase commands return to the original shell and some spawn a subshell and return only when you type exit or hit CTRL/D. For example, when your default UNIX shell on login is ksh, and you type bash at your prompt, you created a child process whose parent is a ksh. The child will run a bash shell until you exit it and return to the parent ksh. To visualize this you can use a simple perl script Read the comments there. Put it in your HOME directory and remember to do: chmod 755 Log in to a UNIX server and have two xterms open. In one xterm type: ~/ Assuming that your default login shell is ksh and your user name was jkl you would see something like this:

# ~/

Process tree for user jkl:
    |___.  USER     PID    PPID ...
    |___.  jkl    31276 31274 ... -ksh
        |___.  jkl    31737 31276 ... /usr/bin/perl /home/jkl/
            |___.  jkl    31745 31737 ... /bin/ps -ef
    |___.  jkl    31305 31303 ... -ksh 

The eclipses (...) may represent some other processes and things that we are not interested in at this moment. You can see your processes there:

Create a simple script, say myshell and place it in your HOME directory:



echo "This will only be printed after you type exit or hit CTRL/D"

Make sure that you did: chmod 755 myshell to make it executable. Then run it in one of the xterms as ~/myshell. You may see that your UNIX prompt changed but not much more than that. In the other xterm run the script ~/ again. Your output should look something like:

# ~/
Process tree for user jkl:
    |___.  USER     PID    PPID ...

    |___.  jkl    63966 63964  ... -ksh
        |___.  jkl    92013 63966 ... /bin/bash ./myshell
            |___.  jkl    92014 92013 ... bash

    |___.  jkl    64064 64062 ... -ksh
        |___.  jkl    93879 64064 ... /usr/bin/perl /home/jkl/
            |___.  jkl    93880 93879  ... /bin/ps -ef

So what happened here?

Now, type exit in an xterm when you ran the myshell script:

% exit
This will only be printed after you type exit or hit CTRL/D

an if you run the ~/ script in the other window again you will get something like this:

# ~/                                 
Process tree for user jkl:
    |___.  USER     PID    PPID ...

    |___.  jkl    63966 63964 ... -ksh

    |___.  jkl    64064 64062 ... -ksh
        |___.  jkl    75624 64064 ... /usr/bin/perl /home/jkl/
            |___.  jkl    75625 75624  ... /bin/ps -ef

i.e., the xterm that had two nested bash shell processes is back to ksh. Did you notice what happened when you typed exit in the bash xterm? Now, let us repeat the exercise but run the myshell in a different way, as: source ~/myshell (or if it does not like it, type . for source, that is: . ~/myshell). The visual result will be the same, just a possible UNIX prompt change. Again, in the other window type ~/ and see something like this:

# ~/     
Process tree for user jkl:
    |___.  USER     PID    PPID ...

    |___.  jkl    63966 63964 ... -ksh
        |___.  jkl    81036 63966 ... bash

    |___.  jkl    64064 64062  0 14:44 pts/29   00:00:00 -ksh
        |___.  jkl    81140 64064 ... /usr/bin/perl /home/jkl/
            |___.  jkl    81141 81140 ... /bin/ps -ef

The output is similar (the PIDs of descendants of 64064 ksh process changed since those are new processes). However, the bash shell process with PID 81036 is no longer doubly nested. But still no message that follows the bash command in the myshell script is printed. Why the change? Since source (or .) command does not spawn a new shell to run the script, but runs the commands inside the existing shell. But since bash process started inside the script waits for your input, nothing that follows it will be executed until you type exit. And when you type it, you will get:

% exit
This will only be printed after you type exit or hit CTRL/D

and running ~/ in the other xterm afterward will show the picture that we have see before:

# ~/                                 
Process tree for user jkl:
    |___.  USER     PID    PPID ...

    |___.  jkl    63966 63964 ... -ksh

    |___.  jkl    64064 64062 ... -ksh
        |___.  jkl    96729 64064 ... /usr/bin/perl /home/jkl/
            |___.  jkl    96730 96729 ... /bin/ps -ef

Now, assuming that you have a view in the ClearCase called jkl_koolapp_2.4.1 create a script in your HOME directory and call it check_if_view_set(and remember to chmod):


cleartool setview jkl_koolapp_2.4.1
cleartool pwv -short

echo == Sorry no go with: 'cleartool pwv -short'
echo == This will not be executed until you exit from a shell that was
echo == spawn by ClearCase, and when you exit, you will exit also
echo == jkl_koolapp_2.4.1 view. And when you exit the view,
echo == you will have no view and you are FUBAR.

and run it as ~/check_if_view_set. Even the prompt will not change. Running the ~/ in the other xterm reveals what just happened:

# ~/                                 
Process tree for user jkl:
    |___.  USER     PID    PPID ...

    |___.  jkl    63966 63964 ... -ksh
        |___.  jkl    22089 63966 ... /bin/bash /home/jkl/check_if_view_set
            |___.  jkl    22090 22089 ... ksh

    |___.  jkl    64064 64062 ... -ksh
        |___.  jkl    25013 64064 ... /usr/bin/perl /home/jkl/
            |___.  jkl    25014 25013 ... /bin/ps -ef

Now type the cleartool pwv -short in the xterm where you ran your /check_if_view_set:

# cleartool pwv -short

Well... You are in the view (i.e., the command in the script: cleartool setview jkl_koolapp_2.4.1 worked fine, but nothing was done afterward inside the script check_if_view_set. When you type exit in the same xterm you will get:

# exit
** NONE **
== Sorry no go with: cleartool pwv -short
== This will not be executed until you exit from a shell that was
== spawn by ClearCase, and when you exit, you will exit also
== jkl_koolapp_2.4.1 view. And when you exit the view,
== you will have no view and you are FUBAR.

And if you ran your faithful companion my_pstree in the other xterm you would see that you are back to two plain shells:

# ~/                                 
Process tree for user jkl:
    |___.  USER     PID    PPID ...

    |___.  jkl    63966 63964 ... -ksh

    |___.  jkl    64064 64062 ... -ksh
        |___.  jkl    37832 64064 ... /usr/bin/perl /home/jkl/
            |___.  jkl    37833 37832 ... /bin/ps -ef

What is the conclusion? RTFM. You need to read the ClearCase man pages. You also need to try, use some toy commands and toy views so you do not mess up anything. For example, for testing, if there is a remote possibility that you can rename 100 important elements, you list the elements to be renamed first, an only when you are ABSOLUTELY SURE that the right elements will be renamed, you put the dangerous command in, i.e., you do it on live body with a real scalpel. Test, test, test... There is a lot of things that man pages will not tell you. If you wrote a toy script like:

cat > /tmp/temp_cc_$$ <<EOF 
echo == I am inside the view: 
cleartool pwv -short  
cd /vobs/www/patentviewer/ 
echo == I changed to the top directory of my project: 
echo Unix directory listing 
ls -l  
echo ClearCase directory listing 
cleartool ls -l 
chmod 755 /tmp/temp_cc_$$ 
cleartool setview -exec /tmp/temp_cc_$$ jkl_koolapp_3.2.10  
You would get something like:
# ~/check_if_view_set_good                       
== I am inside the view:
== I changed to the top directory of my project:
Unix directory listing
total 18
drwxrwxr-x  2 jkl ccusr 1591 Jul 28 12:27 bin
drwxrwxr-x  3 jkl ccusr   99 Jun 23 10:14 conf
drwxrwxr-x  2 jkl ccusr    0 Jan 21  2007 lib
drwxrwxr-x  5 jkl ccusr  285 Jul 28 16:59 www
ClearCase directory listing
directory version      bin@@/main/jkl_koolapp_3.2.10/1\
          Rule: element * .../jkl_koolapp_3.2.10/LATEST
directory version      conf@@/main/8\
          Rule: element * /main/LATEST -mkbranch jkl_koolapp_3.2.10
directory version      lib@@/main/3\
          Rule: element * /main/LATEST -mkbranch jkl_koolapp_3.2.10
directory version      www@@/main/1\
          Rule: element * /main/LATEST -mkbranch jkl_koolapp_3.2.10

and feel the force. Your script would execute and you would get back to the original ksh in which you executed it (you can verify it with the as usual). Do not be too happy though. This one was an easy toy script... The real scripts are harder to make and require a lot of testing and foresight. I cannot give you my actual scripts that I use, since they include the work of others. But I will give a taste of it, by showing you a script that I wrote for myself from scratch to create a view. You can use it as a start up example and create a better one. The script assumes that team members work on their private branches in their private views. Also, the views have the same names as branches and their names have to be composed from the user name, project name, and iteration version, for example: jbl_koolapp_3.1.2. The script tries to enforce the naming, who is allowed to do things, etc. Again... To even try it in your environment, you will have to carefully go through the source, and modify the bogus names there. But maybe, you will find there some ideas that will be helpful. Good luck. The bash script example is here: mk_usr_koolapp_view. Frankly, I would write it in perl and made it much shorter, but it is an example. As you can see, even this small script depends very tightly on policies and local environment. For this reason, it would be very hard (at least for me) to cook up something generic, but I tried to make it "adaptive". Enjoy, and write more scripts and share... I will be grateful for corrections, since, as you can see, I am a ClearCase beginner and use it since I had been told to do so...

Disclaimer: All the stuff written above is most likely nonsense. If you believed any of this, it is your problem. Do not sue me... You have been warned!
P.S. Sorry very much... Me speaks English very small and them thinks me is dummied person and pays me little... If me speaks good, them think me is the genius and them pay big salary to me... You learn speak very big and wise and you not need work hard and only talk much... Join the Republicano-Democratic Party and become a rich politician and crook...

Jan Labanowski
jkl at ccl dot net
Greg's Law of Evolution: Only tasty animals and plants have a chance for survival.
Jan's extension: They also have to be helpless and easy to prepare...