p4 fstat

Synopsis

Dump file info in format suitable for parsing by scripts.

Syntax

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

Description

The p4 fstat command dumps information about each file, with information for each field on a separate line. 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.

The only argument required for the p4 fstat command, is the file[rev] argument. All other options relate to limiting the set of files operated on or controlling the amount and display of information for the selected 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.
  • Use the -m max option to limit the output to the first max files.
  • 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 option.
  • To limit output to the set of fields specified in a fields argument, use the -T fields option. The list of field names can be separated by spaces or commas.

The head type fields, for example, headTime, return information for the file revision provided for the file argument. If no specific revision is given, it returns information for the head revision.

Form Fields

The fields shown will vary with the selected file.

Field Name Description Example/Notes

attr-name

Attribute value for name

attr-myAttr critical

attrProp-name

Set if attr-name is a propagating attribute

attrProp-myAttr

clientFile

Local path to file (in local syntax by default, or in Perforce syntax with the -Op option)

For files containing the special characters @, #, *, and %, the clientFile displays the special character.

/staff/userid/src/file.c

(or //workspace/src/file.c in Perforce syntax)

depotFile

Depot path to file .

For files containing the special characters @, #, *, and %, the filename is displayed containing the ASCII expression of the character’s hexadecimal value.

//depot/src/file.c

movedFile

Name in depot of moved to/from file

//depot/src/file.c

path

Local path to file

//workspace/src/file.c

isMapped

Set if the file is mapped to current client workspace

isMapped

shelved

Set if file is shelved

shelved

headAction

Action taken at head revision, if in depot

one of add, edit, delete, branch, move/add, move/delete, integrate, import, purge, or archive.

headChange

Head revision changelist number, if in depot

124

headRev

Head revision number, if in depot

124

headType

Head revision type, if in depot

text, binary, text+k, etc. (see “File Types”.)

headCharset

Head charset

for unicode files

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

headModTime

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

movedRev

Head revision of moved file

157

haveRev

Revision last synced to workspace, if on workspace

23

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.

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.

fileSize

File length in bytes (requires -Ol option)

63488

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.

action

Open action, if opened in your workspace

one of add, edit, delete, branch, move/add, move/delete, integrate, import, purge, or archive.

type

Open type, if opened in your workspace

A Perforce file type

charset

Open charset

(for unicode files)

actionOwner

User who opened the file, if open

A Perforce username

workRev

open revision, if opened

 

change

Open changelist number, if opened in your workspace

75331

resolved

The number, if any, of resolved integration records

5

unresolved

The number, if any, of unresolved integration records

2

reresolvable

The number, if any, of re-resolvable integration records

1

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@ws1
...... otherOpen1 user2@ws2
...... otherOpen2 user3@ws3

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

otherLock

otherLockn

For each user with the file locked, the workspace and user holding the lock

user123@workstation9

Because only one user at a time can 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, move/add, move/delete, integrate, import, purge, or archive.

otherChangen

For every changelist with the file open, the changelist

75612

openattr-name

For every changelist with the file open, the attribute value for name

attr-name

openattrProp-name

Set if attr-name is a propagating attribute

attrProp-name

ourLock

Present and set to null if the current user has the file locked, otherwise not present

ourLock

resolveActionn
resolveBaseFilen
resolveBaseRevn
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, if sorted.

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

-A pattern

Restrict displayed attributes to those that match the specified pattern. For example, for the selected files, -A foo* displays only attributes whose name starts with foo.

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

When used with the -Ro option, only pending changes are considered to ensure that files opened for add are included. This option also displays the change description.

-F filter

List only those files that match the criteria specified by filter. See Usage Notes for a discussion of filters.

Filtering is not optimized with indexes for performance.

-L

For scripting purposes or automated reporting processes: report file information on a list of valid file arguments in full depot syntax with a valid revision number. File specifications that do not meet these requirements are silently ignored.

-m max

Produce fstat output for only the first max files.

-Oa

Output attributes set by p4 attribute.

-Od

Output the digest of an attribute.

-Oe

Output attribute values encoded as hex.

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

p4 fstat -e shelvedChange -Rs -Ol reports the file size and digest of files shelved at the specified change.

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

-r

Sort the output in reverse order.

-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. You must use this option to get pending changes.

-Rr

Limit output to open files that have been resolved.

-Rs

Limit output to shelved files. Requires -e changelist option.

p4 fstat -e shelvedChange -Rs -Ol reports the file size and digest of files shelved at the specified change.

-Ru

Limit output to open files that are unresolved.

-Sd

Sort by date.

-Sh

Sort by have revision.

-Sr

Sort by head revision.

-Ss

Sort by filesize.

-St

Sort by filetype.

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

-U

Include files in the unload depot when displaying data. See p4 unload for details.

g-opts

See “Global Options”.

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. The usual comparison operators (=, >, <, >=, and <=) are available. Regular expression matching is supported by the regular expression matching operator (~=).

The following filter expression filters for files of a certain size whose headType field is set to text.

-F "fileSize > 100000 & headType=text"

Filters used for fstat are case-sensitive. 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.

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

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.

To search for text containing characters that are filter expression operators, escape the characters with a backslash (\) character. To match the backslash character, escape it with an additional backlash (\\). Using backslashes to escape search queries has two special cases: you can escape the Perforce "..." wildcard with \..., and you can search for empty fields with \0.

The behavior of comparison operators depends on the type of field you’re comparing against. All fields that fstat processes are text fields. The equality operator (=) or case-insensitive 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, because they match the file if any word in the specified field matches the provided value. Relational operators are always case-sensitive. 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.

Examples

p4 fstat file.c

Displays information on file.c.

p4 fstat //....c@20,@now

Displays information on all .c files after the checking-in of files under changelist 20.

p4 fstat -Os file.c

No client workspace information lines (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 -F "clientFile=c:\\ws\\file.c" //depot/main/...

If a path contains backslashes, escape them with backslashes.

p4 fstat -F "clientFile~=c:\\ws\\[Ff]ile.c" //depot/main/...

Use the ~= regular expression modifier to specify a regexp that matches File.c and file.c.

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