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 ] 
     [ -R ] [ -t <time-spec> ][--use_time_basis_for_overlap]
     [ [ -Fx ] -l <list-file> | <element-list> ]

Status of external files in your workspace:

accurev stat -x [ -f<format(s)> ] [ -R ] [ --ignore ]
     [ [ -Fx ] -l <list-file> | <element-list> ]

Status of versions in a specified stream:

accurev stat { -b | -s <stream> } [ -f<format(s)> ] [ -adDio] [--use_time_basis_for_overlap]
     [ -t <time-spec> ] [ [ -Fx ] -l <list-file> | <element-list> ]

element-selection options:

-a -d -D -e -i -k -L -m -n -o -p -U -x -X --ignore --outgoing

-f option format letters:

[ i | I ] [ 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 in the AccuRev Concepts Guide> for a detailed description of virtual versions and real versions.
status indicators 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.
  • (slink) — the element is a symbolic 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.)
  • (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.
  • (subtwin) — one of the directories in the element’s path has (twin) status. Only one of the (twin) directories and its content can be accessed through the pathname; the other(s) can be accessed through their unique element-IDs. To resolve (subtwin) status, the actual (twin) parent directory must be resolved by renaming and/or defuncting all but one of the twin directories.
  • (stranded) — the element is active in the workspace, but cannot be accessed through the file system. This can occur in several situations:

    • There is no pathname to the element, because the element’s directory (or a higher-level directory) was removed from the workspace or stream.
    • (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.
    • The element’s directory (or a higher-level directory) is cross-linked, making another version appear at the pathname of the active version.

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 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.

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

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.

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.

-e <eid>

Select the file element with the specified element-ID. You can use this option instead of specifying the name of an element. If specified, this option takes precedence over other options, such as -a. If you also specify a <list-file> or <element-list>, it is ignored.

-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:

i: Select all files and directories, even if they are excluded by the value of the .acignore file. (See the -x description.)

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.

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.

-m

Select only modified elements. Can be used with -d.

-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.

-o

Select only elements with overlaps in the workspace or stream, which require a merge. See also -B.

-O

Override the optimized search for modified files. When -O is used, all files are considered, even those whose modification times have not changed since the last time the workspace was updated or searched for modified files. Having to check all files, regardless of modification time, slows stat performance. See Optimized Search for Modified Files above.

-p

Select only elements that are pending promotion from the workspace or stream.

-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.

--use_time_basis_for_overlap

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.

-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).

--ignore

Specify a pattern of elements; external elements matching this pattern are ignored by the stat command. The --ignore option can be used multiple times for the same command, but each instance can specify only one pattern. For example:

accurev stat -x --ignore="*.obj" --ignore="*.txt" --ignore="!file1.txt"

Can also be used to specify the pathname of a text file that contains one or more patterns. For example:

accurev stat -x --ignore="@c:\work\my_ignore.txt"

Note that the patterns expressed using the --ignore option take precedence over patterns expressed using the .acignore file.

--outgoing

Display all files in the workspace or stream with one or more of the following statuses: (member), (modified), (missing), or (external). Can be used with -i to return any (stranded) elements.

-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, "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.

Time keyword: now

Transaction number as a positive integer: e.g. 146 or 23965

Transaction number keyword: highest

When using the –t option, take into account the possibility of a timewarp. The AC_SYNC environment variable (see AccuRev User Preferences) determines how a timewarp will be handled. See also System Clock Synchronization in the AccuRev Admin 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. Wildcards are not expanded. 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

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.

accurev stat -s tbase1 --use_time_basis_for_overlap

See Also

add , files

Techniques for Selecting Elements