ls
Lists VOB-resident objects, elements
loaded into a snapshot view, and view-private objects in a directory
SYNOPSIS
- ls [ –r·ecurse | –d·irectory ]
[ –l·ong | –s·hort ]
[ –vob·_only
- | –vie·w_only ]
[ –nxn·ame ] [ –vis·ible ]
[ pname ... ]
DESCRIPTION
The ls command lists VOB-resident
objects, elements loaded into a snapshot view, and view-private objects in
a directory.
The default listing includes this information:
- The name
of each element cataloged in the current directory, with the version ID of
the particular version in the view. Also included is the version selector
part of the config spec rule that selects this version. In a snapshot view,
you see the message <rule info unavailable> if ls encounters
errors.
- The name
of each view-private object in the current directory
- In a dynamic
view, the name of each derived object (DO) visible in the view, along with
its unique DO ID
The listing for an element or a derived object
in a dynamic view may also include an annotation that indicates an unusual
or noteworthy state. For example, the listing for an element that has been
checked out to your view identifies the version that was checked out:
Annotations Common to All View Types
The following annotations may appear when you
issue ls from any type of view:
- eclipsed
- No version of the element is selected because
a view-private object with the same name exists in your view. Typical occurrence:
you create a view-private file in your view; then an element with the same
pathname is created in another view. In your view, an ls –vob_only shows
the element to be eclipsed.
- eclipsed by checkout
- (Appears only when you use the –vob_only option)
No version from the element's version tree is selected, because the element
has been checked out in this view, and a checked-out version always eclipses
all checked-in versions.
- checkedout but eclipsed
- The element has been checked out in this view,
but there is no CHECKEDOUT config spec rule; thus,
the checked-out version is not visible in the view.
- checkedout but removed
- The element was checked out in this view, but
the view-private file was subsequently removed. You may have deleted the file.
ClearCase and ClearCase LT remove it (in effect) when you check out a
file with checkout –out or when
you check out a DO version.
Note: If a file element
has several names, by virtue of one or more VOB hard links, checking out the
element under one name causes all the other names to
be listed with this annotation. (The element is checked out, but there are
no view-private files with the other names.)
- no version selected
- The element is not selected by any config spec
rule or is selected by a –none config spec rule.
- error on reference
- The element is selected by an –error config
spec rule.
UNIX-Only Annotations Common to All View Types
- view––>vob hard link
- The object is a view-private (operating system
level) hard link to an object in VOB storage.
Annotations Specific to Dynamic Views
The following annotations may appear when you
issue ls from a dynamic view:
- no config record
- (Shareable derived objects only) The derived
object's data container is still stored in the view, but the derived object
in the VOB database (and, typically, its associated configuration record)
have been deleted by rmdo. This can occur
only in the view in which the derived object was originally built.
- disputed checkout
- The element is considered to be checked out by
the view_server but is not so indicated in the VOB
database (or vice versa). This can occur during the short interval in which
a checkin or checkout is in progress. For information about view_server,
see the Administrator's Guide.
- removed with white out
- The derived object was winked in by, and is
still referenced by, the current view, but it has been forcibly removed from
the VOB database with rmdo. The derived
object is not recoverable.
Annotations Specific to Snapshot Views
The following annotations may appear when you
issue ls from a snapshot view:
- not loaded
- The element is not loaded into the snapshot
view. Either there are no load rules specifying the element, or the version-selection
rules do not select any version of the element.
- loaded but missing
- A version of the element was loaded into the
view, but you have deleted or renamed the file in the view. To copy the version
back into the view, use the cleartool get command (note that generates a hijacked file)
or update the snapshot view, specifying the pathname to the missing file.
- hijacked
- The version in the view was modified without
being checked out.
- overridden
- The element is loaded in the snapshot view,
but its file type is not the same as the corresponding object in the VOB;
or the element is not loaded in the snapshot view, but an object with the
same name exists in the view.
- special selection
- The version you checked in (and, hence, the
version currently in the view) is not the version that the config spec selects
from the VOB. For more information, refer to the section, “Actions
Taken in the View” in the checkin reference
page.
- nocheckout
- The version hijacked in the view is no longer
the version the config spec selects from the VOB. To prevent losing changes
in the version selected by the config spec, you cannot check out the hijacked
file. To check in your modifications, you must fix the hijack condition:
- Rename
the hijacked file and update the file.
- Check
out the version from which you hijacked the file.
- Copy
your hijacked file over the checked-out version.
- Merge
from the current version to your checked-out version.
You can now check in your version.
(You can use the graphical update tool
to do the checkout and merge operations.)
- deleted version
- The version currently in the view has been
removed from the VOB (for example, by the rmver command).
Use the update command to copy a valid
version into the view.
Elements Suppressed from the View
The listing includes elements selected with –none and –error config
spec rules, and elements that are not selected by any config spec rule. UNIX
commands, such as ls(1) and cat(1),
return not found errors when accessing such
elements. You can specify such elements in commands that access the VOB database
only, such as describe, lsvtree,
and mklabel.
OPTIONS AND ARGUMENTS
Handling of Directory Arguments
- Default
- For each pname that
specifies a directory element, ls lists
the contents of that directory, but not the contents of any of its subdirectories.
Note: This includes
directories in version-extended namespace, which represent elements and their
branches. For example, specifying foo.c@@/main/bug403 as
an argument lists the contents of that branch: all the versions on the branch.
- –r·ecurse
- Includes a listing of the entire subtree below
any subdirectory included in the top-level listing. VOB symbolic links are
not traversed during the recursive descent.
- –d·irectory
- Lists information on a directory itself, rather
than its contents.
Report Format
- Default
- The default report format is described in the Description section.
- –l·ong
- For each object, lists the config spec rule
that matches the object and classifies each object. The classification can
be one of: version, directory version, file element, directory element, view-private
object, derived object, derived object version, or symbolic link. For each
derived object, ls –long indicates
whether the DO is nonshareable, unshared, promoted, or shared.
- –s·hort
- Restricts the listing of each entry to its
version-extended pathname only.
- –nxn·ame
- Lists simple pathnames instead of version-extended
pathnames.
VOB/View Restriction
- Default
- The listing includes both objects in VOB storage
and objects in view storage.
- –vob·_only
- Restricts the listing to objects in the VOB
storage, including versions of elements and VOB links. This may also add some
entries to the listing: those for the underlying elements that are eclipsed
by checked-out versions.
- –vie·w_only
- Restricts the listing to objects that belong
logically to the view: view-private files, view-private directories, and view-private
links; checked-out versions; and all derived objects visible in the view.
Note: Checked-out
directories are listed by –vob_only, but not by –view_only.
Note: Derived objects
visible in the view are listed by –view_only (but not –vob_only),
regardless of whether they are (or ever have been) shared.
- –vis·ible
- Restricts the listing to objects visible to
the operating system listing command.
Specifying the Objects to Be Listed
- Default
- The current working directory (equivalent
to specifying a dot ( . ) as the pname argument).
If you don't specify any other options, all files and links in the current
working directory are listed; all subdirectory entries are listed, but not
the contents of these subdirectories.
- pname ...
- Restricts the listing to the specified files,
directories, and/or links. pname may be a view-
or VOB-extended pathname to list objects that are not in the view, regardless
of whether the view is a snapshot view or a dynamic view (see pathnames_ccase).
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 some examples, output is wrapped
for clarity.
- List
the VOB-resident objects and view-private objects in the current working directory.
- List
the objects in the current working directory, with annotations.
- List
only the view-private objects in the current working directory.
- List
the contents of the directory in extended namespace that corresponds to the main branch
of element util.c.
- List
the directory version that is visible in the current view:
SEE ALSO
checkin, checkout, config_spec, describe, get,
lsprivate,
lsvtree,
mklabel,
pathnames_ccase,
rmdo, rmver, uncheckout, update