IPnom Home • Manuals • ClearCase

# Rational ClearCase Commands Reference

Keyword Live Search (10 results max):
Type in part of a ClearCase command in the search box.

## find

Uses a pattern, query, or expression to search for objects

### APPLICABILITY

ProductCommand type
ClearCasecleartool subcommand
ClearCase LTcleartool subcommand

Platform
UNIX
Windows

### SYNOPSIS

• Find objects visible in the directory structure seen in the current view:
find pname ... selection-options action-options

• Find all objects in the VOB:
find [ pname... ] –a·ll [ –vis·ible | –nvi·sible ] selection-options action-options

• Find objects throughout all mounted VOBs:
find –avo·bs [ –vis·ible | –nvi·sible ] selection-options action-options, selection-options:
–nam·e pattern
–dep·th | –nr·ecurse | –d·irectory
–cvi·ew
–gro·up group-name
–typ·e { f | d | l } ...
–fol·low
–nxn·ame
–ele·ment query
–bra·nch query
–ver·sion query
ClearCase and ClearCase LT action-options (at least one required, multiple allowed):
–pri·nt
–exe·c command-invocation
–ok command-invocation ...

### DESCRIPTION

The find command starts with a certain set of objects, selects a subset of the objects, and then performs an action on the subset. The selected objects can be elements, branches, versions, or VOB symbolic links. The action can be to list the objects or to execute a command on each object, either conditionally or unconditionally.

Typically, you start with all objects in a directory tree as seen in your view. You can also start with all objects in one or more VOBs, regardless of they are visible in a particular view.

Note: The find command is similar to the UNIX find(1) command. Only a limited set of the standard find options are supported; the way that commands are invoked on selected objects (–exec and –ok options) differs from find(1).

None.

### OPTIONS AND ARGUMENTS

#### Specifying the Starting Set of Objects

Default
None. You must specify one of the following:
• One or more elements, using pname arguments

• One or more VOBs, using the –all option

• All mounted VOBs, using the –avobs option

Note: Processing all VOB elements using –all or –avobs is an order of magnitude faster than going through its entire directory tree by specifying the VOB's root directory as a pname argument. With these options, the order in which elements are processed and/or reported is very different from directory-tree order.

pname ...
One or more file and/or directory elements. find starts with the elements, branches, and versions that are part of the specified file elements and the subtrees under the specified directory elements.

–a·ll
With pname arguments, modifies the meaning of each argument to specify its entire VOB, not just a single file or directory. Without any pname arguments, specifies the VOB containing the current working directory.

Note: When you use find –all, only one instance of an element is reported, even if one or more VOB hard links point to the element. Either the element name or one of the VOB hard links is displayed.

–avo·bs
By default, find starts with all the elements, branches, and versions in all the VOBs mounted on the local host. A snapshot view issues a warning if all mounted VOBs have not been loaded into the view. This option depends on the MVFS, and so has no meaning for snapshot-view-only hosts.

If the CLEARCASE_AVOBS EV is set to a colon-separated list of VOB tags (in UNIX; in Windows, list items must be separated by semicolons), this set of VOBs is used instead.

#### Considering Objects That Are Not Currently Visible

Default
All elements in the VOB are included, whether or not they are visible in the view.

–vis·ible
Includes only those elements, along with their branches and versions, that are visible (have a standard pathname) in the view.

–nvi·sible
Includes only those elements, along with their branches and versions, that are not visible (do not have a standard pathname) in the view.

#### Selecting Elements by Using Standard Criteria

The following options use the specified criteria to select subsets of objects.

–nam·e pattern
Selects the subset of objects whose element names match the specified file-name pattern. pattern must be a leaf name. (See the wildcards_ccase reference page.)

–dep·th
Causes directory entries to be processed before the directory itself.

–nr·ecurse
For each directory element, selects the objects in the element itself, and in the file and directory elements within it, but does not descend into its subdirectories.

–d·irectory
For each directory, examines only the directory itself, not the directory or file elements, or VOB symbolic links it catalogs.

–cvi·ew
Modifies the set of objects selected by the –element, –branch, and –version queries (if any).

If you did not specify –version, replaces each element and branch with the version that is currently in the view. (No substitution is performed on VOB symbolic links.)

If you did specify –version, further restricts the subset to versions that are currently in the view.

Selects only those objects in the subset of elements owned by user login-name.

–gro·up group-name
Selects only those objects in the subset of elements belonging to group group-name.

–typ·e f , –typ·e d, –typ·e l
Selects the subset of objects of a certain kind: file elements (f), directory elements (d), or VOB symbolic links (l). To include multiple kinds of objects, group the key letters into a single argument (–type fd) or use multiple options (–type f –type d).

–fol·low
Traverses VOB symbolic links during the walk of the directory tree.

#### Use of Extended Pathnames

Default
find submits the objects it selects to the specified action using extended pathnames, such as foo.c@@ (element), foo.c@@/main (branch), or foo.c@@/main/5 (version).

–nxn·ame
Removes the extended naming symbol (by default, @@) and any subsequent version ID or branch pathname from the name of each selected object. Duplicate names that result from this transformation are suppressed. In effect, this option transforms extended names into standard operating system names; it also transforms names of branches or versions into names of elements.

#### Selecting Elements by Using Queries

The options in this section select a subset of objects by using the VOB query language, which is described in the query_language reference page. You can use these options in any combination. They are always applied in this order, successively refining the set of selected objects: 1) –element; 2) –branch; 3) –version. The result of applying one or more of these options is a set of objects at the finest level of granularity: all versions if you used –version; all branches if you used –branch; all elements if you used –element. If you use none of these options, the set includes elements and VOB symbolic links. There is no way to use a query to select a set of VOB symbolic links.

–ele·ment query
Selects element objects using a VOB query; all of the selected element's branches and versions are also selected. Using this option with a brtype query makes find –all much faster in a large VOB where the specified branch type exists on a relatively small number of elements.

–bra·nch query
From the set of objects that survived the element-level query (if any), selects branch objects using a VOB query; all of a selected branch's versions are also selected.

–ver·sion query
From the set of objects that survived the element-level and branch-level queries (if any), selects version objects using a VOB query.

#### Specifying the Action

Default
None. You must specify an action to be performed on the selected objects. You can specify a sequence of several actions, using two –exec options, or –exec followed by –print, and so on.

–pri·nt
Lists the names of the selected objects, one per line.

–exe·c command-invocation
UNIX and Windows—Execute the specified command once for each selected object.

Windows—If you invoke a command built in to the Windows shell (for example, cd, del, dir, or copy), you must invoke the shell with cmd /c. For example:

–exec "cmd /c copy %CLEARCASE_PN% %HOME%"

If a path within command-invocation contains spaces, you must enclose it in quotation marks. For example, in cleartool single-command mode (note the backslash used to escape the second quotation mark):

–exec "cmd /c copy %CLEARCASE_PN% \"c:\find results""

In cleartool interactive mode (no escape character needed):

–exec 'cmd /c copy %CLEARCASE_PN% "c:\find results"'

–ok command-invocation
For each selected object, displays a confirmation prompt; if you respond yes, executes the specified command.

When using the –exec or –ok command invocation, do not use braces ({ }) to indicate a selected object or use a quoted or escaped semicolon to terminate the command. Instead, enter the entire command as a quoted string; use one or more of these environment variables to reference the selected object:

CLEARCASE_PN
Pathname of selected element or VOB symbolic link

CLEARCASE_XN_SFX
Extended naming symbol (default: @@)

CLEARCASE_ID_STR
Branch pathname of a branch object (\main\rel2_bugfix); version ID of a version object (\main\rel2_bugfix\4); null for an element

CLEARCASE_XPN
Full version-extended pathname of the selected branch or version (concatenation of the three preceding variables)

### EXAMPLES

The UNIX examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX shell or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

Note: In the UNIX examples that follow, arguments and output that show multicomponent VOB tags are not applicable to ClearCase LT, which recognizes only single-component VOB tags. In this manual, a multicomponent VOB tag is by convention a two-component VOB tag of the form /vobs/vob-tag-leaf—for example, /vobs/src. A single-component VOB tag consists of a leaf only—for example, /src. In all other respects, the examples are valid for ClearCase LT.

• List all file elements in and below the current working directory.

cmd-context find . –type f –print
./Makefile@@
./hello.c@@
./hello.h@@
./msg.c@@
./util.c@@

This listing includes the extended naming symbol. The –nxname option suppresses this symbol.

• List all objects owned by user smg throughout all mounted VOBs.

cmd-context find –avobs –user smg –print
\work_vob\hw\util.c@@
\work_vob\hw\hello.c@@
\smg_tmp\bin@@\main\6\misc\main\3\text@@
\smg_tmp\bin@@\main\6\misc\main\3\Makefile@@
\smg_tmp\bin@@\main\6\misc\main\3\test.c@@
...

• List the version labeled REL1 for each element in or below the current working directory.

cmd-context find . –version "lbtype(REL1)" –print
.@@/main/1
./Makefile@@/main/1
./hello.c@@/main/2

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

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

• List all versions that have a QAed attribute with the string value "Yes".

cmd-context find . –version 'QAed == "YES"' –print
.\Makefile@@\main\2
.\hello.c@@\main\4
.\hello.h@@\main\1
.\util.c@@\main\2
.\util.c@@\main\rel2_bugfix\1

• List the standard name of each element that has (or contains a branch or version that has) a BugNum attribute with the value 189.

cmd-context find . –nxname –element 'attr_sub(BugNum,==,189)' –print
./hello.c

• For each element that has had a merge from the rel2_bugfix branch to the main branch, archive the current version of the element to your home directory.

cmd-context find . –element merge (\main\rel2_bugfix,\main) ^
–exec 'cmd /c copy %CLEARCASE_PN% %HOME%'

• For each element that has had a merge from the rel2_bugfix branch to the main branch, archive the current version of the element to a tar(1) file in your home directory.

cmd-context find . –element "merge(/main/rel2_bugfix, /main)" \
–exec 'echo $CLEARCASE_PN >> /tmp/filelist' % tar –cvf$HOME/rel2bugmerge.tar cat /tmp/filelist
% rm /tmp/filelist

• If any element's most recent version on the main branch is missing label REL3, label it.

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

• Attach a Testing attribute with string value "Done" to all versions labeled REL2. Note that the double-quote characters that enclose the string value must themselves be escaped or quoted:

cmd-context find . –ver 'lbtype(REL2)'\
–exec 'cleartool mkattr Testing \"Done\" $CLEARCASE_XPN' • Conditionally delete all branches of type experiment. cmd-context find . –branch brtype(experiment) ^ –ok 'cleartool rmbranch –force %CLEARCASE_XPN%' • (ClearCase only) Change all elements currently using storage pool my_cpool to use pool cdft instead. cmd-context find . –all –element 'pool(my_cpool)' \ –exec 'cleartool chpool cdft$CLEARCASE_PN'

• Obsolete elements that are no longer visible.

cmd-context find . –all –nvisible –exec 'cleartool lock –obsolete %CLEARCASE_PN%'

• List merges (recorded by hyperlinks of type Merge) involving versions located at the ends of branches named gopher.

cmd-context find . –version 'version(.../gopher/LATEST)' –print \
–exec 'cleartool describe –short –ahlink` Merge \$CLEARCASE_XPN'
.@@/main/gopher/1
-> /vob1/proj/src@@/main/146
./base.h@@/main/gopher/1
-> /vob1/proj/src/base.h@@/main/38
./main.c@@/main/gopher/1
-> /vob1/proj/src/main.c@@/main/42

• In the current directory and its subdirectories, list element versions that are on the branch main_dev and that were created in May of this year and that are not the LATEST versions.

cmd-context find . –version "{brtype(main_dev) && created_since(30-Apr) &&
(! created_since(31-May)) && (! version(\main\main_dev\LATEST))}" -print