find
Uses a pattern, query, or expression
to search for objects
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
–use·r login-name
–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).
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.
- –use·r login-name
- 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):
In cleartool interactive
mode (no escape character needed):
- –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.