find

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

APPLICABILITY

ClearCase (cleartool subcommand), Attache (command)

SYNOPSIS

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 their visibility in a particular view.

PERMISSIONS AND LOCKS

Permissions Checking: No special permissions required. Locks: No locks apply.

OPTIONS AND ARGUMENTS

SPECIFYING THE STARTING SET OF OBJECTS.  Default: None. You must specify one of the following:

NOTE: Processing all of a VOB's 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.
In Attache, arguments of the form @pname can be used to add the contents of the local file pname as pathname arguments. The pathname arguments can contain wildcards, and must be listed in the file one per line, or also be of the form @pname. Specifying a relative pathname for @pname begins from Attache's startup directory, not the working directory, so a full local pathname is recommended.
-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 there is one or more VOB hard links that 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 or on the helper host (Attache). A snapshot view issues a warning if all mounted VOBS have not been loaded into the view.

If the CLEARCASE_AVOBS EV is set to a semicolon-separated list of VOB-tags, this set of VOBs is used instead. In Attache, this environment variable must be set in the helper process.

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 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 (ClearCase) or wildcards (Attache) 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 ClearCase or Attache extended names into standard operating system names (in Attache, for the helper host); it also transforms names of branches or versions into names of elements. In Attache, this selection-option is always applied when the -get action is used.

SELECTING ELEMENTS USING QUERIES.  The options in this section select a subset of objects 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: first -element, then -branch, then -version. The result of applying one or more of these options is a set of objects at the finest level of granularity level: all versions if you used -version, or else all branches if you used -branch, or else 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 a 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. In Attache, you cannot specify -get with any of the other actions.

(Attache only) -get [ -compress ] [ -ove·rwrite | -nov·erwrite ] [ -pti·me ] [ -log pname ]

Causes files matching a query to be downloaded to the workspace. See the get reference page for explanations of the specifications following the -get keyword.
-pri·nt

Lists the names of the selected objects, one per line.
-exe·c command-invocation

Execute the specified command (in Attache, on the helper host) once for each selected object. 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 embed 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 (in Attache, on the helper host).

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

Examples including 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 command interpreter prompt. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt. In Attache, cmd-context represents the workspace prompt.

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.

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@@
...
cmd-context find . -version "lbtype(REL1)" -print
.@@\main\1
.\Makefile@@\main\1
.\hello.c@@\main\2
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
...
cmd-context find . -name '*.h' -element 'lbtype_sub(REL2) ^
|| lbtype_sub(REL3)' -print
.\hello.h@@
cmd-context find . -name '*.h' -element 'lbtype_sub(REL2) || lbtype_sub(REL3)' -get
cmd-context find . -name '*.c' -avobs -version '{created_since(yesterday)}' -get
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
cmd-context find . -nxname -element attr_sub(BugNum,==,189) -print
.\hello.c
cmd-context find . -element merge(\main\rel2_bugfix,\main) ^
-exec 'cmd /c copy %CLEARCASE_PN% %HOME%'
cmd-context find . -version 'version(\main\LATEST) && ! lbtype(REL3)' ^
-exec 'cleartool mklabel -replace REL3 %CLEARCASE_XPN%'
cmd-context find .-ver lbtype(REL2) ^
-exec 'cleartool mkattr Testing \"Done\" %CLEARCASE_XPN%'
cmd-context find . -branch brtype(experiment) ^
-ok 'cleartool rmbranch -force %CLEARCASE_XPN%'

Attache:

cmd-context find . -branch brtype(experiment) -ok 'cleartool rmbranch -force %CLEARCASE_XPN%'
cmd-context find . -all -element pool(my_cpool) ^
-exec 'cleartool chpool cdft %CLEARCASE_PN%'

Attache:

cmd-context find . -all -element pool(my_cpool) -exec 'cleartool chpool cdft %CLEARCASE_PN%'
cmd-context find . -all -nvisible -exec 'cleartool lock -obsolete %CLEARCASE_PN%'
.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
cmd-context find . -version "{brtype(main_dev) && created_since(30-Apr) &&
(! created_since(31-May)) && (! version(\main\main_dev\LATEST))}" -print

SEE ALSO

describe, ls, query_language, wildcards, wildcards_ccase



Feedback on the documentation in this site? We welcome any comments!
Copyright © 1999 by Rational Software Corporation. All rights reserved.