AccuRev® Command-Line Reference : stat

stat
show the AccuRev status
of elements or file system objects
Usage
Status of elements in your workspace:
accurev stat [ -f<format(s)> ] [ <element-selection-option> ]
[ -B ] [ -L ] [ -M ] [ -O | -O2 ] [ -R ] [ -t <time-spec> ]
[ [ -Fx ] -l <list-file> | <element-list> ]
Status of external files in your workspace:
accurev stat -x [ -f<format(s)> ] [ -R ] [ [ -Fx ] -l <list-file> |
<element-list> ]
Status of versions in a specified stream:
accurev stat { -b | -s <stream> } [ -f<format> ] [ -adDio ]
[ -t <time-spec> ] [ [ -Fx ] -l <list-file> | <element-list> ]
element-selection options:
-a -d -D -i -k -L -m -n -o -p -U -x -X
-f option format letters:
[ a | r ] [ f | d ] [ l ] [ e ] [ x ] [ k ] [ n ] [ o ]
Description
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:
name of element
The pathname of the element, relative to the depot’s top-level directory.
virtual version
The virtual version-ID of the version currently in the stream.
(real version)
The real version-ID (enclosed in parentheses) of the version currently in the stream. See Promotion: Real Versions and Virtual Versions on page 6 of the AccuRev Concepts Manual for a detailed description of virtual versions and real versions.
status indicators
(Not included if you use the -a option) One or more of the keywords listed in the following section.
Status Indicators
An element’s status consists of one or more of the following status indicators.
Link-related indicators:
(elink) — the element is an element link.
(There is no status indicator for a file element or directory element.)
(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.
Presence of the element in the workspace:
(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.
(external) — the file or directory has not been placed under version control. (It’s in the workspace tree, but not in the workspace stream.) See Pathname Optimization: ACCUREV_IGNORE_ELEMS and .acignore on page 21 in AccuRev Technical Notes.
(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 on page 49 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:
(dynamic stream only) There are one or more defunct elements at a given pathname, along with one non-defunct element. The defunct element(s) have (stranded) status.
Changes to the element in the workspace:
(modified) — the file has been modified in the workspace since the most recent update or keep. See Optimized Search for Modified Files: the Scan Threshold below.
(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.
(pending) — the element is “pending” in the workspace if the version in the workspace has changes that have not yet been promote’d to the parent stream. The set of pending elements includes both (kept) elements and (modified) elements.
Relationship to the version in the backing stream:
(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.
Depot-Relative Pathnames
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:
src/commands/base.h
(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):
/home/jsmith/gizmo_dvt_jsmith/src/commands/base.h   (UNIX/Linux absolute pathname)
c:\gizmo_dvt_jsmith\src\commands\base.h             (Windows absolute pathname)
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)
Optimized Search for Modified Files: the Scan Threshold
When stat searches your workspace for files that have been modified (with any of the options -n, -m, -p, -o), 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 doesn’t consider files whose timestamps precede the workspace’s scan threshold (the time that the workspace was most recently updated or otherwise searched for modified files).
Note: this optimization is not used in a search for external files (stat -x).
stat adjusts the scan threshold after a modified-files search (-n, -m, -p, or -o option) as follows:
If you also specify the -O option, stat might find one or more modified elements whose timestamps precede the current scan threshold. In this case, the scan threshold is moved backward in time, to the point just before the earliest timestamp among the modified elements found.
It is possible for your workspace to get new files with old timestamps: certain file-copy and file-archive utilities can preserve timestamps; the AccuRev commands co, pop, purge, revert, and update preserve timestamps when copying versions into the workspace if the environment variable ACCUREV_USE_MOD_TIME is set. In such situations, the timestamp optimization causes stat to silently ignore relevant 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.
Note: AccuRev 5.4 introduced a second, optional timestamp optimization methodology to work around the above issues. See the “Local, Client-Based Timestamp Optimization” section of the AccuRev On-Line Help Guide for details.
Improving ‘stat’ Performance
The timestamp optimization described above produces the greatest performance boost when it enables stat to ignore a large number of files based on their timestamps. If stat seems sluggish, try executing an update command or a stat -n command. If the workspace contains a significant number of files whose timestamps fall between the previous update and the current time, the optimization will enable a subsequent execution of stat to ignore these files. For more on this topic, see The Update Algorithm on page 38 of AccuRev Technical Notes.
Options
-a
Select all elements in the stream. You cannot also specify a list of elements, either on the command line or with a list-file (-l).
-b
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.
-B
Also display the status of all versions in the backing chain of streams above the workspace stream. This reveals any deep overlaps or underlaps for the element.
-d
Select only active elements (those in the default group) of the workspace or stream.
-D
Select only defunct elements in the workspace or stream.
-f<format(s)>
 
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:
-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: Prior to AccuRev Release 4.9, this was the default behavior; now you must specify -fo. As of Release 4.9, 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.
You can use appropriate combinations of the above options — for example, -fda or -frl. The following additional keyletters can be used in combination with each other, and with the ones above:
-e: Display the element-ID.
-k: Display the element type (that is, data type) of this version; different versions of an element can have different element types; see Controlling the Element Type and Exclusive File Locking State in the add reference page.
-i
Select only stranded elements: members of the default group that no longer have a pathname in the workspace or stream.
-k
Select only kept elements.
-L
Allows you to specify the full pathname of a directory in an AccuRev workspace. If this option is omitted, AccuRev defaults to the current workspace. Using -L has the same effect as checking the Search in Selected Folder option in the Java GUI.
-m
Select only modified elements. Can be used with -d. With this option, stat also adjusts the workspace’s scan threshold — see Optimized Search for Modified Files: the Scan Threshold above.
-M
Restrict the listing to elements that are missing from the workspace tree.
-n
Select only modified elements that are not in the workspace’s default group. With this option, stat also adjusts the workspace’s scan threshold — see Optimized Search for Modified Files: the Scan Threshold above.
-o
Select only elements with overlaps in the workspace or stream, which require a merge. See also -B. With this option, stat also adjusts the workspace’s scan threshold — see Optimized Search for Modified Files: the Scan Threshold above.
-O
Don’t optimize the search for modified files — that is, don’t ignore files whose modification times precede the workspace’s scan threshold. Having to check all files, regardless of modification time, slows stat performance. See Optimized Search for Modified Files: the Scan Threshold above.
-O2
Use the local, client-based timestamp optimization methodology introduced in AccuRev 5.4.
-p
Select only elements that are pending promotion from the workspace or stream. With this option, stat also adjusts the workspace’s scan threshold — see Optimized Search for Modified Files: the Scan Threshold above.
-R
Process all the elements in the specified directory tree(s). Use “.” to specify the current working directory.
-s <stream>
Display the status of the version in the specified stream (or snapshot), not the file in the workspace. See the description of <element-list> below for notes on how to specify the element(s). See also -b.
-U
Select only underlap files and directories.
-x
Select only external files and directories.
-X
Display files and directories that have been excluded from the workspace or stream (or from a higher-level stream) with the excl command. These objects are listed with the status indicator (excluded).
-t <time-spec>
Stat elements based on a point in time or a transaction number. A time-spec can be any of the following:
Time in <YYYY/MM/DD HH:MM:SS> format: e.g. 2007/08/07 20:27:15. Note that you might need to use quotes in composing the argument following –t; the entire argument must be interpreted by the command shell as a single token.
When using the –t option, take into account the possibility of a timewarp. The AC_SYNC environment variable (see AccuRev User Preferences on page 6) determines how a timewarp will be handled. See also section System Clock Synchronization on page 31 of the AccuRev Administrator’s Guide.
-Fx
Signals that <list-file> (see the -l option) is an XML-format file, not a flat text file. Example:
<elements>
  <e eid="2"></e>
  <e eid="200"></e>
</elements>
–l <list-file>
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. There is no provision for comment lines in the file.
If you use this option, any <element-list> specified is silently ignored.
<element-list>
One or more element names, separated by whitespace. If you also specify a <list-file> using the –l option, this <element-list> is silently ignored.
You can specify patterns, using the wildcard characters ? (match any character) and * (match any 0 or more characters).
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.
Examples
List all modified elements in the workspace:
> accurev stat -m
List all modified elements in the workspace’s default group:
> accurev stat -md
List all modified elements in the current directory:
> accurev stat -m *
List all elements in the default group of stream tulip_test:
> accurev stat -s tulip_test -d
List all .doc files in the current working directory, displaying the data-type of each one:
> accurev stat -ffk *.doc
List all elements in the stream as of transaction id 23564:
> accurev stat -t 23564 -a
List all elements in the stream as of January 5, 2010, at 1:00.:00:
> accurev stat -t "2010/01/05 01:00:00" -a
List all elements in Stream1’s default group as of transaction id 18543:
> accurev stat -t 18543 -s Stream1 -d
List all elements in Stream1’s default group as of January 5, 2010:
> accurev stat -t "2010/01/05 01:00:00" -s Stream1 -d
List all deep overlap elements, even if they occur above a time basis stream, and return the results in XML:
accurev stat -s Stream_1 -o -B -fox
See Also
add, files
Techniques for Selecting Elements on page 13
The Update Algorithm on page 38 of AccuRev Technical Notes

AccuRev, Inc.
Phone: 781-861-8700
Fax: 781-861-8704
support@accurev.com