accurev stat [ -f<format(s)> ] [
<element-selection-option> ][ -B ] [ -L ] [ -M ] [ -O ] [ -R ] [ -t
<time-spec> ][--use_time_basis_for_overlap]
[ [ -Fx ] -l
<list-file> |
<element-list> ]
accurev stat { -b | -s <stream> } [ -f
<format(s)> ] [ -adDio] [--use_time_basis_for_overlap][ -t
<time-spec> ] [ [ -Fx ] -l
<list-file> |
<element-list> ]
-f option format letters:
The stat command displays the status of files in your workspace, or of elements in a specified stream. The most basic use of
stat is to show the current version of an element in your workspace stream. It can also be used to find out which elements in your workspace you have modified or which elements are ready to be promoted.
The stat listing includes:
|
•
|
(missing-target) — For an element link, the target element is not present in the workspace or stream. This can occur if the target element is removed from the workspace tree by an operating system command. It can also result from an incl -b or excl command. For a symbolic link, there is no object at the target pathname.
|
|
•
|
(modified-target) — For an element link, the target element has been modified (either a content change or a namespace change) in the workspace or stream.
|
|
•
|
(defunct-target) — For an element link, the target element has (defunct) status in this workspace or stream.
|
|
•
|
(nonexistent-target) — For an element link, the target element does not appear at all in this stream or workspace. This occurs when the target element is defunct’ed then promote’d to the parent stream.
|
|
•
|
(corrupted) — For an element link in a workspace, AccuRev and the operating system disagree on the link target. That is, the target element recorded in the AccuRev repository differs from the target in the operating system’s instantiation of the link in the workspace tree. This can occur if you modify or replace a link using operating system commands instead of AccuRev commands.
|
A cross-linked element (see (xlinked) below) gets corrupted status if AccuRev does not overwrite the element during execution of the
Include from Stream command, because the element has
(modified) or
(kept) status in the workspace. This should not occur during normal operation.
|
•
|
(defunct) — the element has been marked for removal from the workspace stream with the defunct command. The element has already been removed from the workspace tree (local disk storage); it gets removed from the workspace stream (in the depot) when you promote the element to the backing stream.
|
|
•
|
(excluded) — the element does not appear in the workspace because it has been excluded, using the Include/Exclude facility. For file elements, it’s more likely that the exclusion was explicitly set on the directory in which the file resides, or in a higher-level directory that includes the file. See the incl, excl, and incldo reference pages.
|
|
•
|
(xlinked) — this version of the element appears in the workspace or stream by virtue of a cross-link ( incl -b command) — either on the element itself or on its parent directory or a higher-level directory.
|
|
•
|
(missing) — the workspace “should” include a version of this element, but doesn’t. This occurs when you delete version-controlled files from the workspace tree using operating system commands. If an operation causes the target of an element link to be removed from a workspace, AccuRev removes the element link, also, causing it to have (missing) status.
|
|
•
|
(twin) — the element is one of multiple elements in the workspace that exist at the same pathname. At most one of these elements can be accessed through the pathname; the other(s) can be accessed through their unique element-IDs. See Version Control of Namespace-Related Changes in AccuRev Technical Notes.
|
|
•
|
(stranded) — the element is active in the workspace, but cannot be accessed through the file system. This can occur in several situations:
|
|
•
|
(kept) — a new version of the element has been created with keep, move, defunct, or undefunct, and the file has not subsequently been modified, promote’d to the backing stream, or purge’d.
|
|
•
|
(member) — the element is “active” in the workspace (is in the workspace stream’s default group). The commands that create a new version, listed above, also make the element active. So do the commands anchor, co, and revert.
|
|
•
|
(backed) — the version in the workspace stream is the same as the version in the backing stream. And you have not changed the element since the last time you promote’d or purge’d it, or since the most recent update of your workspace.
|
|
•
|
(stale) — the element needs to be updated, because the version in the backing stream has changed since the workspace’s latest update. And since you have not changed the element in your workspace, it can be safely updated.
|
|
•
|
(overlap) — the element has changed both in the backing stream and in your workspace. This indicates that a merge is required before you can promote your changes to the backing stream. Prior to AccuRev 4.6, “underlap” files were considered to have “overlap” status.
|
|
•
|
(underlap) — similar to overlap: the element has changed both in the backing stream and in your workspace, but the changes in your workspace have already been promoted to the backing stream. (More precisely, your version is an ancestor of the backing stream’s version.) In many cases, the most appropriate course of action is to purge the changes from your workspace, restoring the version that was in the backing stream at the time of the workspace’s most recent update. In other cases, a merge-promote sequence is most appropriate. Prior to AccuRev 4.6, “underlap” files were considered to have “overlap” status.
|
A depot implements a (version-controlled) directory tree; thus, every element in the depot has a pathname within that directory tree. For example, depot gizmo might contain a top-level directory named
src, which contains a subdirectory named
commands, which contains a file name
base.h. The element’s pathname within the depot is:
(Adjust the slashes to suit your operating system.) By default, stat lists files and directories using such
depot-relative pathnames. It uses the distinctive prefix
/./ (UNIX/Linux) or
\.\ (Windows) to indicate a depot-relative pathname:
/./src/commands/base.h (UNIX/Linux depot-relative pathname)
\.\src\commands\base.h
(Windows depot-relative pathname)
stat can also list files using absolute pathnames (
-fa option):
Likewise, stat can list files using relative pathnames (
-fr option). If the current working directory is
src, then the relative pathname of file
base.h is:
./commands/base.h (UNIX/Linux relative pathname)
.\commands\base.h
(Windows relative pathname)
When stat searches your workspace for files that have been modified (with any of the options
-n,
-m,
-p,
-o) or that have not yet been added to AccuRev (
-x), it must scan the entire workspace on your hard drive. This might involve many thousands of files, and is potentially quite time-consuming. In these searches,
stat defaults to using a
timestamp optimization to speed its search for modified files: it does not consider files whose timestamps have not changed since the last time the workspace was updated or searched for modified files.
Use the -O option to have
stat dispense with the optimization and consider all files, regardless of timestamp, in its search for modified files.
Display the status of the version in the backing stream, not the file in the workspace. See also
-s.
Note: To handle files that have been renamed in the backing stream,
stat first looks up the specified filename in the workspace, gets the EID, and uses the EID to find the correct file in the backing stream. If the specified name is not found in the workspace, then the backing stream is searched. In any case, the name of the file as it currently exists in the backing stream is what gets displayed.
By default, stat displays both files and directories; for each one, it displays the location as a
depot-relative pathname (see
Depot-Relative Pathnames above), status indicators, the virtual version-ID, and the real version-ID in parentheses. Use one or more of the following format letters to restrict displays to either files or directories and to control other formatting:
i: Select all files and directories, even if they are excluded by the value of the
.acignore file. (See the
-x description, and
Specifying Ignore Patterns for External Objects of
AccuRev Technical Notes .)
I: Select only those files and directories specified by the value of the
.acignore file.
a: Display locations as absolute pathnames.
r: Display locations as relative pathnames (relative to the current working directory).
f: Display files only.
d: Display directories only.
l: Display locations only (no status indicators or version-IDs).
n: Split each element’s listing onto two lines: the first contains the depot-relative pathname; the second contains the status information. (This option overrides all other
-f... options.)
o: Display deep overlap elements that exist above a time basis stream.
Note: The default behavior without
-fo is to stop at a time basis (same as
stat -o -B), to improve performance and return fewer irrelevant results.
When combined with the XML option (-fox), this option causes a "
timeBasisStream=" attribute to be appended to the XML output for overlap elements that exist above the time basis stream.
v: Display the target of an element link or symbolic link. If an element link is part of a multiple-link chain, only the element at the end of the chain is displayed.
x: Display the results in XML format.
Select only stranded elements: members of the default group that no longer have a pathname in the workspace or stream.
Use the workspace's update level or the stream's time basis to identify overlap instead of using the current time.
When this option is used, AccuRev shows (overlap) status for a file only if the file was overlapped at the time indicated by the workspace's update level or the stream's time basis.
|
•
|
Time in <"YYYY/MM/DD HH:MM:SS"> format, " 2007/08/07 20:27:15", for example. Note that you must use quotes when specifying time-spec as YYYY/MM/DD HH:MM:SS to ensure that the entire argument is interpreted by the command shell as a single token.
|
Signals that <list-file> (see the
-l option) is an XML-format file, not a flat text file. Example:
Process the elements listed in <list-file>. This must be a text file, with one element name per line. Extra whitespace is not allowed; make sure there are no empty lines and no leading or trailing white space around the filenames. Wildcards are not expanded. There is no provision for comment lines in the file.
If you use -s to display the status of a non-workspace stream, then each name in
<element-list> is interpreted relative to the top-level directory of the depot. Typically, a simple filename like
base.h won’t be valid; instead, use a pathname like
src/include/base.h. Alternatively, use a full
depot-relative pathname, like
/./src/include/base.h.
List all .doc files in the current working directory, displaying the data-type of each one:
List all elements in Stream1’s default group as of transaction id
18543:
List all elements in Stream1’s default group as of January 5, 2010:
List all elements in stream tbase1, but do not show (overlap) status if the overlap was created at a higher transaction level than
tbase1's time basis.
The Update Algorithm of
AccuRev Technical Notes