IBM Support

Additional examples of the cleartool find command

Question & Answer


Where can you find examples of using the IBM Rational ClearCase "cleartool find" command?


The ClearCase Command Reference manual provides a few samples for using the cleartool find command, however, there are a lot of usage examples that are not covered in that document that would be helpful. The information below is provided to help supplement the information found in the manual.

The cleartool find command is used to locate ClearCase objects within a VOB, and is not restricted by the view's configuration specification (config spec). There are various switches and options available for this command, refer to cleartool man find, or the IBM Rational ClearCase Information Center under the topic of find for more details.

Note: It is not possible to list the elements in a single directory using the cleartool find command. This command operates on file attributes or metadata, and there is no method to query upon a file's location within a directory. All the versions that get returned are for elements that are located in or below the working directory.


The cleartool find command can be used with the QUERY LANGUAGE to take advantage of logical operators. Review the IBM Rational ClearCase Information Center on the topic of query_language (cleartool man query_language) for more details.


Use the cleartool find command with the logical not (!) & and (&&) operators to find all versions for an element that are not labeled with either of two label types in the VOB.

cleartool find . -version !"lbtype(tested) && !lbtype(release) " -print

About *_sub query primitives

When using the ClearCase find command in what circumstances should the *_sub query primitives (attype_sub, label_sub and attr_sub) be used instead of just lbtype or attype?

When the type being queried does not apply to the "level" (-element -branch -version) being queried. For example, query for a label using -element ... labels are only on versions within elements


When searching recursively through the levels for all matches. For example, query for an attribute using -element, attr_sub would recursively search element, branches AND versions of the element for that attribute.

Excluding any elements that do not have both labels, list all versions in the current VOB labeled either REL1 or REL2 but not both.

cmd-context find -all -element '{lbtype_sub(REL1) && lbtype_sub(REL2)}' ^
-version '{(lbtype(REL1) && ! lbtype(REL2)) || ^
(lbtype(REL2) && !lbtype(REL1))}' -print

- (ClearCase only) List each header file (*.h) for which some version is labeled REL2 or REL3.

cmd-context find . -name '*.h' -element 'lbtype_sub(REL2) ^
|| lbtype_sub(REL3)' -print

Without the _sub:
cmd-context find . -version 'version(\main\LATEST) && ! lbtype(REL3)' ^
-exec 'cleartool mklabel -replace REL3 %CLEARCASE_XPN%'


When running a cleartool find command the text can run off the screen, but you can redirect the output to a text file. To capture the data to a file for viewing, printing or use by a script (or other program) the output can be redirected as follows:

  1. To get the STDOUT information add " > file_name.txt" to the end of the command string:
    • cleartool find . -all -print > c:\out.txt
  2. To get both STDOUT and STDERR information add " > file_name.txt 2>&1" to the end of the command string:
    • Windows -- cleartool find . -all -print > c:\out.txt 2>&1
    • UNIX/Linux -- cleartool find . -all -print >& /tmp/out.txt


Examples of the cleartool find command usage:

  • Find the latest versions of all elements in a directory and execute a cleartool rmname on them:

    cleartool find . -version version(\main\LATEST) -exec 'cleartool rm

  • Find an element with a particular name:

    cleartool find . -name "file name" -print

  • Find all the latest versions of all files with a .txt extension and list those versions:

    cleartool find . -name "*.txt" -version version(\main\LATEST) -print

  • Find the latest version of elements with a particular string in their name and list those versions:

    cleartool find . -name "*ada*" -version version(\main\LATEST) -print

  • Find all element versions with a given label that are not on a given branch:
  • Windows:

    cleartool find -all -version "lbtype_sub(MYLABEL) && !brtype(mybranch)" -print

    UNIX and Linux:

    cleartool find -all -version 'lbtype_sub(MYLABEL) && !brtype(mybranch)' -print

  • Find checkouts on a specific branch:

    • Checked out on main:
      M:\base_dmhnt_view\Support>cleartool find . -version "brtype(main)"
      -print | find "CHECKEDOUT"

    • Checked out on branch, BR3:
      M:\base_dmhnt_view\Support>cleartool find . -version "brtype(BR3)"
      -print | find "CHECKEDOUT"


    UNIX and Linux:
    • Checked out on main:
      /usr/atria/bin/cleartool find . -version "brtype(main)"
      -print | grep CHECKEDOUT


    • Checked out on branch, BR3:
      /usr/atria/bin/cleartool find . -version "brtype(BR3)"
      -print | grep CHECKEDOUT


  • Find, list out and count the number of elements in VOB, refer to technote 1125941

  • Find and list dates when a particular label was attached to all versions:

    It is sometimes important to know when a given label was applied to a version of an element, as opposed to when that version was created. This note explains the process used for to create the command line to display the desired information.


    To report the date when the cleartool mklabel command was issued on element foo.c for attaching version label REL1, use the following command:

    UNIX and Linux:
    % cleartool lshistory -minor lbtype:REL1 foo.c

    cleartool lshistory -minor lbtype:REL1 foo.c

    To generate the list of those elements which contain a version with a predetermined label (REL1) attached, use the following syntax of the cleartool find command:

    UNIX and Linux:
    % cleartool find -all -element '{lbtype_sub(REL1)}' -print

    cleartool find -all -element "{lbtype_sub(REL1)}" -print

    The solution is the combination of the cleartool find command with the cleartool lshistory command as follows:

    UNIX and Linux:
    % cleartool find -all -element '{lbtype_sub(REL1)}' -exec 'cleartool lshistory
    -minor lbtype:REL1 $CLEARCASE_PN'

    cleartool find -all -element "{lbtype_sub(REL1)}" -exec "cleartool lshistory
    -minor lbtype:REL1 %CLEARCASE_PN%"

    To reduce the output from the command above to include only those lines which report the date when mklabel was issued, add the following grep or find command:

    UNIX and Linux:
    % cleartool find -all -element '{lbtype_sub(REL1)}' -exec 'cleartool lshistory
    -minor lbtype:REL1 $CLEARCASE_PN' | grep 'make label'

    M:\admin_vu\vob1>cleartool find -all -element "{lbtype_sub(REL1)}" -exec
    "cleartool lshistory -minor lbtype:REL1 %CLEARCASE_PN%" | find "make label"

  • Find all labeled or non-labeled versions that are selected by the view, you can use the combination of -cview and -version with cleartool find in order to achieve the desired result:

    To print all the versions selected by your view:
    cleartool find . -cview -print

    To print all versions selected by your view that have a LABEL applied:
    cleartool find . -cview -version "lbtype(LABEL)" -print

    To print all versions from your view that do not have the LABEL applied:
    cleartool find . -cview -version "!lbtype(LABEL)" -print

    To find versions in which two labels do not exist:
    cleartool find . -ver "! lbtype(REL1) && ! lbtype(REL2)&& version(.../main
    /LATEST)" -print

    To find all elements with any label:


    cleartool find . -type f -exec "cleartool lsvtree -a %CLEARCASE_PN%" | findstr

    ./hello.c@@/main/1 (LABEL100, LABEL99, LABEL98, LABEL97)
    ./foo.xml@@/main/BR1/1 (REL2)
    ./bar.o@@/main/1 (REL1)


    cleartool find . -type f -exec 'cleartool lsvtree -a $CLEARCASE_PN' | grep "("

    ./hello.c@@/main/1 (LABEL100, LABEL99, LABEL98, LABEL97)
    ./foo.xml@@/main/BR1/1 (REL2)
    ./bar.o@@/main/1 (REL1)

  • Find and listing symbolic links:

    UNIX and Linux:

    There are two ways this can be done.

    1. cleartool find -all -type l -exec '/usr/atria/bin/cleartool describe $CLEARCASE_PN'

    % cleartool find -all -type l -exec '/usr/atria/bin/cleartool describe
    symbolic link "/vobs/french/ctlink_import" -> import
    created 25-Feb-03.12:34:39 by Joe_USER (joeuser.syb@lemur)
    User : joeuser : rwx
    Group: syb   : rwx
    Other:          : rwx
    symbolic link "/vobs/french/slink_import" -> import
    created 16-Apr-03.14:02:17 by Joe_USER (joeuser.syb @lemur)
    User : joeuser : rwx
    Group: syb   : rwx
    Other:          : rwx

    2. cleartool find -all -type l -print


    %> cleartool find -all -type l -print


    1. cleartool find . -type l -exec "cleartool describe -fmt \"%n %[slink_text]Tp\n\"

    Y:\VOB_A>cleartool find . -type l -exec "cleartool describe -fmt "%n
    %[slink_text]Tp\n\n\" \"%CLEARCASE_PN%\""

    .\Directory\createsymlink.txt -->..\..\VOB_B\SymlinkFolder\createsymlink.txt

    Note: In the example above, the file createsymlink.txt is located in VOB_A and a symbolic link to this file was created in the SymlinkFolder in VOB_B.

    2. cleartool find -all -type l -print

    Y:\VOB_A>cleartool find -all -type l -print

  • Find latest labels:


    cleartool lshistory -minor <DIRECTORY> |grep "make label" |grep <element name>

    Note: Removing the last grep from the command will list all labels created in that directory.


    cleartool lshistory -minor -r . |findstr /C:"make label"

  • Find and label all element versions before a certain date and time:

    Get all the files in a VOB and store that data in a flat file:

    cleartool find <vobtag> -all -print > <filename1>
    cleartool find <vobtag> -version -print > <filename>

    Get all the files created after the target date/time and store that data in a flat file:

    cleartool find <vobtag> -element "{created_since(target-data-time)}" -print >

    cleartool find <vobtag> -version "{created_since(target-data-time)}" -print >

    Compare the two files to get the 'before version set'.

    Do this by taking the first entry in filename2, then going to filename1 and taking everything that occurs before that line in filename1:

    Save that in a new file, <filename3>

    For every entry in <filename3> execute:

    cleartool mklabel <labelname>

  • Find and label the latest versions on a branch:

    First you should change the view's config spec to look at the desired branch.

  • Then run a sample find command to verify the list of versions that would be labeled:
    cleartool  find . -version 'version(.../bugs/LATEST)' -print                    .@@/main/bugs/1                                                        



    Once the above list if verified, modify the find command to include the mklabel command to apply the label to those versions:

    cleartool find . -version 'version(.../bugs/LATEST)' -exec 'cleartool mklabel
    REL3 $CLEARCASE_PN'                                                            

    Created label "REL3" on "." version "/main/bugs/1".                    

    Created label "REL3" on "./bar.c" version "/main/bugs/1".              

    Created label "REL3" on "./foo.c" version "/main/bugs/2".    

  • Find all elements or versions created between a specific date and time:


    To find elements created between two dates and times:
    cleartool find . -element "{created_since(date1) && !created_since(date2)}"

    To find versions created between two dates and times:
    cleartool find . -version "{created_since(date1) && !created_since(date2)}"

    To narrow the search by user, add -user or created_by, such as to find elements created between date1 and date2 by user1 and modified by user2:
    cleartool find . -user user1 -element "{created_since(date1) &&
    !created_since(date2)&& created_by(user2)}" -print

    Using the query language, you can also restrict the output to specific branches, such as to find versions created since date1 on BRANCH and modified by user1:
    cleartool find . -version "{brtype(BRANCH) && created_since(date1) &&
    created_by(user1)}" -print

  • Find all file elements in a VOB with a particular extension and change the protections:

    to find all file elements in a VOB with a particular extension and change the protections:

    To find all .exe file elements with no spaces in the filenames and add the execute bit for the user ownership:
    cleartool find . -all -name *.exe -print -exec "cleartool protect -chmod u+x -file

    This will find all .bat file elements that have spaces in the filenames and add the execute bit for the group ownership:
    cleartool find . -all -name *.bat -print -exec "cleartool protect -chmod u+x -file

    Note: The syntax can be modified as needed to find different file types and set the protections. Also, the additional quotations are needed to pick filenames that contain spaces.

  • Find and recursively check out elements, refer to technote 1122520.
  • Find and remove labels recursively, refer to technote 1126736.
  • Find all triggers associated with an element, refer to technote 1120633.
  • To List all branches on all elements run the cleartool find command in a directory and search for branches that do NOT have a non-exististent attribute.

    For example...

    cleartool find . -branch '\!attype(dummyname)' -print
  • Windows example: Search the text within a file to find all instances of a particular string:

    Note: Uses the Windows for command.

    for /f %a in ('cleartool lsvtree -all <ELEMENT NAME>') do find "<STRING>" %a


    <ELEMENT NAME> = element which version tree you wish to check
    <STRING> = the search string you wish to look for.


    M:\view\my_test_vob>for /f %a in ('cleartool lsvtree -all test.txt') do find "hi" %a

    Access denied - TEST.TXT@@\MAIN
    ---------- TEST.TXT@@\MAIN\0
    ---------- TEST.TXT@@\MAIN\1
    ---------- TEST.TXT@@\MAIN\2

  • Find all hyperlinks in a VOB and describe them (or run checkvob against them).

    cleartool find . -all -kind all -exec "cleartool describe -ahlink -all

    Note: If needed the 'describe -ahlink -all' can be replace by a 'checkvob -hlinks',

  • Find a particular string in a comment by searching all versions of all elements in a VOB.

    Note: Example syntax includes formatting for the version and the comment:

    cleartool find -all -ver "! lbtype(<non-existing label>)" -exec 'cleartool
    desc -fmt "Version: %n\tComment: %c\n\n" $CLEARCASE_XPN' | grep <the string
    you are looking for>

    cleartool find -all -ver "! lbtype(<non-existing label>)" -exec "cleartool
    desc -fmt \"Version: %n\tComment: %c\n\n\" %CLEARCASE_XPN%" | findstr "<the
    string you are looking for>"

  • Find the value of a specific hyperlink:

    The following command will return a "describe" on each element that is found with the type in the find command.

    cleartool find . -version "hltype(Merge)" -nxname -exec 'cleartool desc
    $CLEARCASE_PN' -print

    From the output of this command the user will get a list of all the elements. Then the user will then need to create a script to parse this output and extract just the names.

  • Replacing label names in a ClearCase VOB

    In the examples below, label type REL1 is replaced with REL2.

    1) If the label type is not globally, simply use the rename command:

    cleartool rename lbtype:REL1 lbtype:REL2

    2) If, in fact, the label is globally defined, this command will result in the following error message:

    cleartool: Error: Operation "rename" not allowed on the local instance of a global label type.
    cleartool: Error: Unable to rename label type from "REL1l" to "REL2".

    Thus, for globally defined label types, it is necessary to use a two step process of:

    - adding REL2 to all instances of REL1
    - removing the REL1 labels

    Here are the steps in detail:
    a) First, create the label type REL2:

    cleartool mklbtype REL2

    b) Find the elements that already have REL1 attached to them so that the new REL2 label can be attached:

    cleartool find . -ver lbtype(REL1) -exec "cleartool mklabel REL2 %CLEARCASE_PN%"

    c) Remove all instances of the REL1 label:

    cleartool find . -ver lbtype(REL1) -exec "cleartool rmlabel REL1 %CLEARCASE_PN%"

    d) If desired, remove the REL1 label type:

    cleartool rmtype -rmall lbtype:REL1

  • Counting the number of versions in a VOB

    Within the VOB, use the command, "cleartool find . -exec 'cleartool lsvtree -a $CLEARCASE_PN' |wc -l". This counts the number of versions in the VOB, including those that are checked out.

  • How to Checkout all elements in a VOB

    From the root of the VOB:

    On Windows:

    cleartool find . -type dfl -exec "cleartool checkout %CLEARCASE_PN%"

    On UNIX:

    cleartool find . -type dfl -exec 'cleartool checkout $CLEARCASE_PN'

  • How to list element versions on a branch but exclude checkedout versions

    The first example lists all element versions including any CHECKEDOUT versions. The second example shows how to list all element versions, but excluding any CHECKEDOUT versions.

    EXAMPLE 1:
    > cleartool find . -version "brtype(bugfix)" -print

    > cleartool find . -version "brtype(bugfix)" -print | grep -v CHECKEDOUT

  • Example optimizing the cleartool find command:

    The below 'ct-find' commands both return the same result set, but the first one takes *hundreds of times longer*!!!.

    The second find isn't faster just because caches are loaded per the first run or anything like that. Going to a new replica and running the optimized find first still gives results in a couple seconds while even then the slower find run subsequently takes minutes still.

    Cleartool find is slower when you are not scoping to the -branch level before looking for the httype criteria on every single "-version" in the element's vtree

    my-view1:7> date ; ct find /vob/cc/sys/makesubsys -follow -dir -version '(hltype(Merge, <-) || hltype(Merge, -> )) &&
    brtype(main)' -print;date Tue Apr 24 11:04:15 PDT 2007
    Tue Apr 24 11:16:28 PDT 2007

    my-view1:8> date; ct find /vob/cc/sys/makesubsys -follow -dir -branch 'brtype(main)' -version '(hltype(Merge, <-) ||
    hltype(Merge, ->))' -print;date Tue Apr 24 11:35:40 PDT 2007
    Tue Apr 24 11:35:42 PDT 2007

  • How to find elements/versions on a specific branch in multiple VOBs:

    Version: cleartool find -avobs -version "brtype(branch)" -print

    Element: cleartool find -avobs -element "brtype(branch)" -print

  • How to find elements and versions with specific comments

    I want to find all elements/versions with specific comments like “Jane changed this on 11-26”

    M:\my_base_view\my_base_vob>cleartool find -all -exec "cleartool lshistory -minor -fmt \"%n\t%c\n\"
    \"%CLEARCASE_XPN%\"" >c:\output.txt

    **This will pipe the output to a file and you would have to grep the file for the specific comments you're looking for.

    M:\my_base_view\my_base_vob>cleartool find . -version !"lbtype(LABEL_NAME)" -exec "cleartool
    describe -long CLEARCASE_PN%" >c:\output2.txt

    **This will search for a nonexistent label

  • How to apply a label to the latest version on a branch where that version was created before a certain date.
    cleartool find . -version "{brtype(main) && ! created_since(4-Feb)}"

    -exec '/opt/rational/clearcase/bin/cleartool mklabel -replace REL99


    In this example, label REL99 will be labeled on the latest version on the main branch
    when that version was created on February 3 or prior.

    The variable $CLEARCASE_XPN must be used so the proper version gets labeled.
    If variable, $CLEARCASE_PN, is used the label will go on the latest version on the main
    branch which is not intended here.

    The -replace option is also needed, otherwise the label will not go on the proper version.

    You should run the command with the -print statement first to verify that the proper versions are getting listed correctly before running the command with the -exec option above:

    cleartool find . -version "{brtype(main) && ! created_since(4-Feb)}"  -print

    UCM Specific Examples

[{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Cleartool","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF015","label":"IRIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"9.0;8.0.1;8.0;7.1.2;7.1.1;7.1;7.0.1;7.0","Edition":"","Line of Business":{"code":"LOB15","label":"Integration"}},{"Product":{"code":"SSSH27","label":"Rational ClearCase"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Cleartool","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"LOB15","label":"Integration"}}]

Document Information

Modified date:
16 June 2018