Question & Answer
Question
Where can you find examples of using the IBM Rational ClearCase "cleartool find" command?
Answer
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
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?
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: GENERAL EXAMPLES: Examples of the cleartool find command usage: Windows: UNIX and Linux: ./bar.c@@/main/bugs/1 ./foo.c@@/main/bugs/2 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".
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.
About *_sub query primitives
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%'
cleartool find . -version version(\main\LATEST) -exec 'cleartool rm
%CLEARCASE_PN%'
cleartool find . -name "file name" -print
cleartool find . -name "*.txt" -version version(\main\LATEST) -print
cleartool find . -name "*ada*" -version version(\main\LATEST) -print
cleartool find -all -version "lbtype_sub(MYLABEL) && !brtype(mybranch)" -print
cleartool find -all -version 'lbtype_sub(MYLABEL) && !brtype(mybranch)' -print
Windows:
M:\base_dmhnt_view\Support>cleartool find . -version "brtype(main)"
-print | find "CHECKEDOUT"
Results:
.@@\main\CHECKEDOUT
M:\base_dmhnt_view\Support>cleartool find . -version "brtype(BR3)"
-print | find "CHECKEDOUT"
Results:
.\coocoo.exe@@\main\BR3\CHECKEDOUT
UNIX and Linux:
/usr/atria/bin/cleartool find . -version "brtype(main)"
-print | grep CHECKEDOUT
Results:
.@@/main/CHECKEDOUT
/usr/atria/bin/cleartool find . -version "brtype(BR3)"
-print | grep CHECKEDOUT
Results:
./coocoo.exe@@/main/BR3/CHECKEDOUT
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"
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)
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
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"
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>
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'
Examples:
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
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.
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
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
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',
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>"
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.
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
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.
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'
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
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
Version: cleartool find -avobs -version "brtype(branch)" -print
Element: cleartool find -avobs -element "brtype(branch)" -print
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
- cleartool find . -version "{brtype(main) && ! created_since(4-Feb)}"
- 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
-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
Related Information
Was this topic helpful?
Document Information
Modified date:
16 June 2018
UID
swg21124425