files

show the status of elements

Usage

accurev files [ -s <stream> ] [ -O ] [ -f <format(s)> ] [ --ignore ]
[ -X ] { <element-list> | -l <list-file> }

Description

The files command lists the AccuRev status of files and directories in a workspace or reference tree.

•	For each file element you specify, it lists the element itself.

•	For each directory element you specify, it lists the contents of the directory (the file and directory elements within it).

•	If you don’t specify any elements on the command line, it lists the contents of the current working directory.

As this example shows ...

\.\src\brass.c capon\1 (5\1) (backed)

... the listing for each element includes:

•	the element’s depot-relative pathname

•	the virtual version of the element that is currently in your workspace (or in the stream you specified with -s)

•	the corresponding real version of the element (version-ID in parentheses)

•	the status of the element in your workspace or the specified stream

The various status flags — (backed), (kept), etc. — are the same as those displayed by the stat command.

Optimized Search for Modified Files

By default, files uses a timestamp optimization to speed its search for files that have been modified in your workspace: it does not consider files whose timestamps have not changed since the last time the workspace was updated or searched for modified files.

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 files to silently ignore relevant files. Use the -O option to have files dispense with the optimization and consider all files, regardless of timestamp, in its search for modified files.

Listing of Defuncted / Deleted Objects

If you remove a file or directory element from your workspace with the defunct command, the files command continues to “see” it:

\.\src\brass.c capon_dvt_john\2 (5\2) (defunct) (kept) (member)

That’s because the element itself is still active in your workspace stream. (You can think of it as actively being changed from present to absent.) The element continues to be listed by files, with the (defunct) status flag, until you promote it or purge it. Promoting the defunct element removes it from the workspace stream, and thus from files listings; purging the element effectively undoes the defunct command, returning the element to (backed) status.

Similarly, if you remove a file or directory element from your workspace tree with an operating system command (such as del or rm), the files command continues to “see” it. That’s because the operating system command doesn’t modify the AccuRev element itself. The status of a deleted element in your workspace is (missing).

Note: The stat and files commands do not include defuncted elements when listing the contents of the parent directory. The operating system’s “list directory” command doesn’t see the defuncted element, because defunct removes the file or directory from the workspace tree.

Options

-s <stream>

Display the status of the element(s) in the specified stream, not in your workspace. See the description of <element-list> below.

-O

Override the optimized the 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 files performance. See Optimized Search for Modified Files above.

-f <format(s)>

Use one or more of the following format letters:

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.

x: Display the results in XML format.

Note: You can combine the x letter with either i or I (-fxi, for example), but the i and I letters are mutually exclusive (-fiI is invalid, for example).

--ignore

 

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

accurev files -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 files -x --ignore="@c:\work\my_ignore.txt"

See Specifying Ignore Patterns for External Objects of AccuRev Technical Notes for more information on specifying ignore patterns for external files.

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

-X

Add excluded elements to the listing.

-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 elements in a non-workspace stream, then each relative pathname in <element-list> is interpreted relative to the depot’s top-level directory. 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 the status of all files in the current directory:

> accurev files

\.\tools\perl\findtags.pl brass2\1 (2\1) (modified)
\.\tools\perl\reporter.pl brass2_john\2 (2\2) (kept) (member)
\.\tools\perl\mail.1 (external)
\.\tools\perl\mail.2 (external)

List the status of all files in subdirectory doc:

> accurev files doc

.\doc\chap01.doc brass2_dvt\1 (2\2) (backed)
.\doc\chap02.doc brass2_john\2 (2\2) (kept) (member)
.\doc\chap03.doc brass2\1 (2\1) (backed)
.\doc\chap04.doc brass2\1 (2\1) (backed)

See Also

stat

Techniques for Selecting Elements

The Update Algorithm of AccuRev Technical Notes