Perforce 2009.1: Command Reference

p4 fstat

Synopsis

Dump file info in format suitable for parsing by scripts.

Syntax

p4 [g-opts] fstat [-F filter -T fields -m max -r] [-c|-e change] [-Ox -Rx -Sx] file[rev]...

Description

The p4 fstat command dumps information about each file, with each item of information on a separate line.

Use the -m max option to limit the output to the first max files.

To change the field on which output is sorted, use one of the -Sx options, and to reverse sort order, use the -r option.

To filter the output on some function of the form fields (for example, all files larger than a certain size and with a certain filetype), use the -F filter flag.

To limit output to the set of fields specified in a fields argument, use the -T fields flag.

The output is best used within a Perforce API application where the items can be accessed as variables, but is also suitable for parsing by scripts.

Form Fields

Field Name	Description	Example/Notes
clientFile	local path to file (in local syntax by default, or in Perforce syntax with the -Op option)	/staff/userid/src/file.c (or //workspace/src/file.c in Perforce syntax)
depotFile	depot path to file	//depot/src/file.c
path	local path to file	//workspace/src/file.c
isMapped	set if mapped client file is synced	set (... isMapped) or not present
headAction	action taken at head revision, if in depot	one of add, edit, delete, branch, or integrate
headChange	head revision changelist number, if in depot	1, 2, 3... n
headRev	head revision number, if in depot	1, 2, 3... n
headTime	Head revision changelist time, if in depot. Time is measured in seconds since 00:00:00 UTC, January 1, 1970	919283152 is a date in early 1999
headRevModTime	Head revision modification time (the time that the file was last modified on the client before submit), if in depot.	919280483 is a date in early 1999
headType	head revision type, if in depot	text, binary, text+k, etc. (see the chapter on File Types.)
haveRev	revision last synced to workspace, if on workspace	1, 2, 3... n
desc	changelist description (if using -e changelist and if the file was part of changelist)	A Perforce changelist
digest	MD5 digest of a file (requires -Ol option)	A 32 hexadecimal digit string
fileSize	file length in bytes (requires -Ol option)	63488
action	open action, if opened in your workspace	one of add, edit, delete, branch, or integrate
type	open type, if opened in your workspace	A Perforce file type
actionOwner	the user who opened the file, if open	A Perforce username
change	open changelist number, if opened in your workspace	1, 2, 3... n
resolved	the number, if any, of resolved integration records	1, 2, 3... n
unresolved	the number, if any, of unresolved integration records	1, 2, 3... n
otherOpen	the number of other users who have the file open, blank if no other users have the file open	1, 2, 3... n, preceded by n records listing the users (0 through n-1) with otherOpenn, otherActionn, and otherLockn fields as applicable. For example: ... otherOpen 3 ...... otherOpen0 user1@cws1 ...... otherOpen1 user2@cws2 ...... otherOpen2 user3@cws3
otherOpenn	for each user with the file open, the workspace and user with the open file	user123@workstation9
otherLock	present and set to null if another user has the file locked, otherwise not present	unset (... otherLock) or not present
otherLockn	for each user with the file locked, the workspace and user holding the lock	user123@workstation9 Because only one user at a time, may lock a file, if n is set, n is always 0.
otherActionn	for each user with the file open, the action taken	one of add, edit, delete, branch, or integrate
otherChangen	for every changelist with the file open, the changelist	A changelist number
ourLock	present and set to null if the current user has the file locked, otherwise not present	unset (... ourLock) or not present
resolveActionn resolveBaseFilen resolveFromFilen resolveStartFromRevn resolveEndFromRevn	Pending integration action, base file, base revision number, from file, starting, and ending revision, respectively.	For pending integration record information, use the -Or option.
totalFileCount	The number of files examined.	Appears in the first file's output when you use the -m max option in conjunction with one of the -Sx or -r sorting options.

Options

-F filter	List only those files that match the criteria specified by filter. Please see the Usage Notes below for a discussion of filters.
-T fields	List only those fields that match the field names specified by fields. The list of field names can be separated by spaces or commas.
-c change	Display only files affected after the given changelist number. This operation is much faster than using a revision range on the affected files.
-e change	Display only files affected by the given changelist number. This option is much faster than using a revision range on the affected files.
-m max	Produce fstat output for only the first max files.
-r	Sort the output in reverse order.
-Of	Output all revisions for the given files, suppressing the other[...] and resolve[...] fields.
-Ol	Output a fileSize field displaying the length of the file and a digest field for each revision. On servers older than release 2005.1, this field may be expensive to compute, particularly for text files with many revisions.
-Op	Display the clientFile in Perforce syntax, as opposed to local syntax.
-Or	Display pending integration record data for files open in the current workspace.
-Os	Shorten output by excluding client workspace data (for instance, the clientFile field).
-Rc	Limit output to files mapped into the current workspace.
-Rh	Limit output to files on your have list; that is, to files synced to the current workspace.
-Rn	Limit output to files opened at revisions not at the head revision.
-Ro	Limit output to open files in the current workspace.
-Rr	Limit output to open files that have been resolved.
-Ru	Limit output to open files that are unresolved.
-St	Sort by filetype.
-Sd	Sort by date.
-Sr	Sort by head revision.
-Sh	Sort by have revision.
-Ss	Sort by filesize.
g-opts	See the Global Options section. The -s global option (which prefixes each line of output with a tag describing the type of output as error, warning, info, text, or exit) can be particularly useful when used with p4 fstat.

Usage Notes

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
Yes	Yes	list

Filters

Use p4 fstat -F filter to limit the list of files to those that meet certain criteria. You can use logical operators on any of the form fields displayed by p4 fstat.

Text matching is case-insensitive. All alphanumeric strings (including words including embedded punctuation) separated by whitespace are indexed as words.

Spaces between search terms in a filter are treated as boolean AND operations. To find files that contain any of the key/value pairs (boolean OR), separate the terms with the "|" character.

Ampersands (&) can be used as boolean ANDs as well; the boolean operators bind in the order &, |, space (highest precedence to lowest precedence). Use parentheses to change the grouping order.

Search results can be narrowed by matching values within specific fields with the filter syntax "fieldname=value". The value must be a single token, including both alphanumeric characters and punctuation.

The wildcard "*" allows for partial word matches. The filter "fieldname=string*" matches "string", "stringy", "stringlike", and so on.

Date fields can be matched by expressing the filter date as yyyy/mm/dd or yyyy/mm/dd:hh:mm:ss. If a specific time is not provided, the equality operator (=) matches the entire day.

The usual comparison operators (=, >, <, >=, and <=) are available.

Additionally, you can use the NOT operator (^) to negate the sense of some comparisons.

To search for text containing characters that are filter expression operators, escape the characters with a backslash (\) character.

The behavior of these operators depends on the type of field you're comparing against:

Field Type	Use of Comparison Operators in Filters
word	The equality operator (=) must match the value in the word field exactly. The relational operators perform comparisons in ASCII order.
text	The equality operator (=) matches the file if the word given as the value is found anywhere in the specified field. The relational operators are of limited use here, since they match the file if any word in the specified field matches the provided value. For example, if a changelist has a text field desc that contains the phrase bug not fixed, and the filter is "desc<fixed", the file matches the filter, because bug<fixed.
line	As for field type text, above.
select	The equality operator (=) matches a file if the value of the named field is the specified word. The relational operators perform comparisons in ASCII order.
date	Dates are matched chronologically. If a specific time is not provided, the operators =, <=, and >= match the entire day.

Other Usage Notes

•	If you use -e changelist# with the -Ro option, only pending changes are considered, so that files open for add are included in the output.

•	The syntax of p4 fstat was changed in Release 2004.2. The older -C, -H, -W, -P, -l, and -s options are supported for compatibility purposes.

•	For files containing the special characters @, #, *, and %, the clientFile displays the special character, and the depotFile displays the filename containing the ASCII expression of the character's hexadecimal value.

•	The size and digest fields are based on the normalized (UNIX linefeed convention) and uncompressed version of the depot file, regardless of how the file is represented when synced to a client workspace.

Examples

p4 fstat file.c	Displays information on file.c
p4 fstat -Rc 20 *.c	Displays information on all .c files affected after the checking-in of files under changelist 20.
p4 fstat -Os file.c	No client workspace information lines (i.e. clientFile) are displayed
p4 fstat -Osl file.c	No client workspace information lines are displayed, but the fileSize and digest lines are displayed.
p4 fstat -Os -Ol file.c	Equivalent to p4 fstat -Osl.
p4 fstat -Ol -F "fileSize < 1024 & headType=text" //depot/main/...	Display information on all text files under //depot/main/... that are smaller than 1024 bytes in length.
p4 fstat -T 'depotFile, headRev' file.c	Display only the depotFile and headRev fields for file.c.

Related Commands

To read additional information about each file	p4 files
To display file information including change descriptions	p4 filelog