Additional examples of the cleartool find command

Technote (FAQ)

Question

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

Answer

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.

Logical operators

About *_sub query primitives

Redirect output to a file

General examples

UCM specific examples

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.

LOGICAL OPERATORS:

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.

Example:

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

Back to top

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

Or

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.


Example:
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 
\dev\testfile.txt@@\main\43
\dev\testfile.txt@@\main\68
\dev\util.c@@\main\50
\dev\util.c@@\main\58
...

- (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 
.\hello.h@@


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

Back to top

REDIRECT OUTPUT TO A FILE:

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

Back to top

GENERAL EXAMPLES:

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 
  %CLEARCASE_PN%'
  
  
• 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:
  
  Windows:
  
  • Checked out on main:
    M:\base_dmhnt_view\Support>cleartool find . -version "brtype(main)" 
    -print | find "CHECKEDOUT" 
    
    Results:
    .@@\main\CHECKEDOUT 
    
  • Checked out on branch, BR3:
    M:\base_dmhnt_view\Support>cleartool find . -version "brtype(BR3)" 
    -print | find "CHECKEDOUT" 
    
    Results:
    .\coocoo.exe@@\main\BR3\CHECKEDOUT
    
  
  UNIX and Linux:
  
  • Checked out on main:
    /usr/atria/bin/cleartool find . -version "brtype(main)" 
    -print | grep CHECKEDOUT 
    
    Results:
    .@@/main/CHECKEDOUT
    
  • Checked out on branch, BR3:
    /usr/atria/bin/cleartool find . -version "brtype(BR3)" 
    -print | grep CHECKEDOUT 
    
    Results:
    ./coocoo.exe@@/main/BR3/CHECKEDOUT
    
    
• Find, list out and count the number of elements in VOB, refer to technote 1125941
  
  

  Back to top

  
  
• 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.
  
  Example:
  
  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
  
  Windows: 
  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
  
  Windows: 
  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'
  
  Windows: 
  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'
  
  Windows: 
  M:\admin_vu\vob1>cleartool find -all -element "{lbtype_sub(REL1)}" -exec 
  "cleartool lshistory -minor lbtype:REL1 %CLEARCASE_PN%" | find "make label"
  
  

  Back to top

• 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:
  
  Windows:
  
  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)
  
  UNIX/Linux: 
  
  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)
  
  

  Back to top

• 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'
  
  Example:
  % cleartool find -all -type l -exec '/usr/atria/bin/cleartool describe 
  $CLEARCASE_PN' 
  symbolic link "/vobs/french/ctlink_import" -> import 
  created 25-Feb-03.12:34:39 by Joe_USER (joeuser.syb@lemur) 
  Protection: 
  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) 
  Protection: 
  User : joeuser : rwx 
  Group: syb   : rwx 
  Other:          : rwx
  
  2. cleartool find -all -type l -print
  
  Example:
  
  %> cleartool find -all -type l -print 
  /vobs/french/ctlink_import 
  /vobs/french/slink_import
  
  Windows:
  
  1. cleartool find . -type l -exec "cleartool describe -fmt \"%n %[slink_text]Tp\n\"
  \"%CLEARCASE_PN%\""
  
  Example:
  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
  
  Example:
  Y:\VOB_A>cleartool find -all -type l -print
  Y:\VOB_A\test\paul_link.txt
  Y:\VOB_A\test\eric_link.txt
  Y:\VOB_A\test\john_link
  Y:\VOB_A\import2@@\main\10\migration9
  Y:\VOB_A\import2@@\main\9\migration8
  
  
• Find latest labels:
  
  UNIX:
  
  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.
  
  
  Windows:
  
  cleartool lshistory -minor -r . |findstr /C:"make label"
  
  
  

  Back to top

• 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>
  or
  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 >
  <filename2>
  or
  cleartool find <vobtag> -version "{created_since(target-data-time)}" -print >
  <filename2>
  
  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>
  
  

  Back to top

• 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                                                        

  ./bar.c@@/main/bugs/1                                                  

  ./foo.c@@/main/bugs/2    

  
  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".     
  

  Back to top

• Find all elements or versions created between a specific date and time:
  
  Examples:
  
  To find elements created between two dates and times:
  cleartool find . -element "{created_since(date1) && !created_since(date2)}" 
  -print
  
  To find versions created between two dates and times:
  cleartool find . -version "{created_since(date1) && !created_since(date2)}" 
  -print
  
  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
  
  

  Back to top

• Find all file elements in a VOB with a particular extension and change the protections:
  
  Examples 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
  %CLEARCASE_PN%" 
  
  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
  ""%CLEARCASE_PN%"""
  
  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.
  
  

  Back to top

  
  
• 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
  .@@/main
  ./A1.txt@@/main
  ./A1.txt@@/main/A
  ./A1.txt@@/main/A/B
  ./A1.txt@@/main/A/B/D
  ./A1.txt@@/main/A/C
  ./A1.txt@@/main/A/E
  ./D1@@/main
  ./D1/D2@@/main
  ./D1/aaa@@/main
  ./E1@@/main
  ./E1/D2@@/main
  ./E1/aaa@@/main
  ./lost+found@@/main
  ./main.c@@/main
  ./mergeTo.xml@@/main
  ./mergeTo.xml@@/main/BR1
  
• 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
  
  where: 
  
  <ELEMENT NAME> = element which version tree you wish to check
  <STRING> = the search string you wish to look for.
  
  Example:
  
  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
  hi
  ---------- TEST.TXT@@\MAIN\2
  hi
  
  

  Back to top

• Find all hyperlinks in a VOB and describe them (or run checkvob against them).
  
  cleartool find . -all -kind all -exec "cleartool describe -ahlink -all
  \"%CLEARCASE_XPN%\""
  
  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:
  
  UNIX/Linux:
  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>
  
  Windows:
  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>"
  
  

  Back to top

• 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
  
  

  Back to top

• 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'
  
  

  Back to top

• 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
  ./a.c@@/main/bugfix/0
  ./a.c@@/main/bugfix/1
  ./a.c@@/main/bugfix/2
  ./a.c@@/main/bugfix/CHECKEDOUT
  ./golf.c@@/main/bugfix/0
  ./golf.c@@/main/bugfix/1
  
  EXAMPLE 2
  > cleartool find . -version "brtype(bugfix)" -print | grep -v CHECKEDOUT
  ./a.c@@/main/bugfix/0
  ./a.c@@/main/bugfix/1
  ./a.c@@/main/bugfix/2
  ./golf.c@@/main/bugfix/0
  ./golf.c@@/main/bugfix/1
  
  

  Back to top

• 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
  /vob/cc/sys/makesubsys@@/main/71
  /vob/cc/sys/makesubsys@@/main/86
  /vob/cc/sys/makesubsys@@/main/87
  /vob/cc/sys/makesubsys@@/main/88
  /vob/cc/sys/makesubsys@@/main/89
  /vob/cc/sys/makesubsys@@/main/90
  /vob/cc/sys/makesubsys@@/main/91
  /vob/cc/sys/makesubsys@@/main/92
  /vob/cc/sys/makesubsys@@/main/93
  /vob/cc/sys/makesubsys@@/main/94
  /vob/cc/sys/makesubsys@@/main/95
  /vob/cc/sys/makesubsys@@/main/96
  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
  /vob/cc/sys/makesubsys@@/main/86
  /vob/cc/sys/makesubsys@@/main/87
  /vob/cc/sys/makesubsys@@/main/88
  /vob/cc/sys/makesubsys@@/main/89
  /vob/cc/sys/makesubsys@@/main/90
  /vob/cc/sys/makesubsys@@/main/91
  /vob/cc/sys/makesubsys@@/main/92
  /vob/cc/sys/makesubsys@@/main/93
  /vob/cc/sys/makesubsys@@/main/94
  /vob/cc/sys/makesubsys@@/main/95
  /vob/cc/sys/makesubsys@@/main/96
  /vob/cc/sys/makesubsys@@/main/71
  Tue Apr 24 11:35:42 PDT 2007
  
  

  Back to top

• 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

$CLEARCASE_XPN'      


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:
Example:

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

UCM Specific Examples

• Find and change ownership of all objects in a UCM PVOB or Component VOB, refer to technote 1146517
  
• How to search a PVOB for Baselines created since a certain date and time , refer to technote 1441502
  



Back to top