p4 fstat
Synopsis
Dump file info in format suitable for parsing by scripts.
Syntax
p4 [g-opts
] fstat [-F filter
] [-L -r -U] [-T fields
] [-m max
] [-c|-e change
]
[-Ox
-Rx
-Sx
] [-A pattern
] 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.
Use the -m
option to limit
the output to the first max
max
files.
To change the field on which output is sorted, use one of the
-S
options, and to reverse
sort order, use the x
-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
option.
filter
To limit output to the set of fields specified in a
fields
argument, use the -T
option. The list of field
names can be separated by spaces or commas.
fields
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 |
---|---|---|
|
Attribute value for name |
|
|
Set if
|
|
|
Local path to file (in local syntax by default, or in Perforce
syntax with the |
(or |
|
Depot path to file |
|
|
Name in depot of moved to/from file |
|
|
Local path to file |
|
|
Set if the file is open for add and it is mapped to current client workspace |
|
|
Set if file is shelved |
|
|
Action taken at head revision, if in depot |
one of |
|
Head revision changelist number, if in depot |
|
|
Head revision number, if in depot |
|
|
Head revision type, if in depot |
|
|
Head charset |
for unicode files |
|
Head revision changelist time, if in depot. Time is measured in seconds since 00:00:00 UTC, January 1, 1970 |
|
|
Head revision modification time (the time that the file was last modified on the client before submit), if in depot. |
|
|
Head revision of moved file |
|
|
Revision last synced to workspace, if on workspace |
|
|
Changelist description (if using |
A Perforce changelist |
|
MD5 digest of a file (requires |
A 32 hexadecimal digit string |
|
File length in bytes (requires |
|
|
Open action, if opened in your workspace |
one of |
|
Open type, if opened in your workspace |
A Perforce file type |
|
Open charset |
(for unicode files) |
|
User who opened the file, if open |
A Perforce username |
|
Open changelist number, if opened in your workspace |
|
|
The number, if any, of resolved integration records |
|
|
The number, if any, of unresolved integration records |
|
|
The number, if any, of re-resolvable integration records |
|
|
The number of other users who have the file open, blank if no other users have the file open |
|
|
For each user with the file open, the workspace and user with the open file |
|
|
Present and set to null if another user has the file locked, otherwise not present |
|
|
For each user with the file locked, the workspace and user holding the lock |
Because only one user at a time can lock a file, if
|
|
For each user with the file open, the action taken |
one of |
|
For every changelist with the file open, the changelist |
75612 |
|
For every changelist with the file open, the attribute value for name |
|
|
Set if |
|
|
Present and set to null if the current user has the file locked, otherwise not present |
|
|
Pending integration action, base file, base revision number, from file, starting, and ending revision, respectively. |
For pending integration record information, use the
|
|
The number of files examined. |
Appears in the first file's output when you use the |
Options
|
Restrict displayed attributes to those that match the specified
|
|
Display only files affected after the given changelist number. This operation is much faster than using a revision range on the affected files. |
|
Display only files affected by the given changelist number. This option is much faster than using a revision range on the affected files. |
|
List only those files that match the criteria specified by
|
|
For scripting purposes, report file information on a list of valid file arguments in full depot syntax with a valid revision number. |
|
Produce fstat output for only the first
|
|
Output attributes set by p4 attribute. |
|
Output the digest of an attribute. |
|
Output attribute values encoded as hex. |
|
Output all revisions for the given files, suppressing the
|
|
Output a
p4 fstat -e |
|
Display the |
|
Display pending integration record data for files open in the current workspace. |
|
Shorten output by excluding client workspace data (for instance,
the |
|
Sort the output in reverse order. |
|
Limit output to files mapped into the current workspace. |
|
Limit output to files on your have list; that is, to files synced to the current workspace. |
|
Limit output to files opened at revisions not at the head revision. |
|
Limit output to open files in the current workspace. |
|
Limit output to open files that have been resolved. |
|
Limit output to shelved files. Requires
p4 fstat -e |
|
Limit output to open files that are unresolved. |
|
Sort by date. |
|
Sort by have revision. |
|
Sort by head revision. |
|
Sort by filesize. |
|
Sort by filetype. |
|
List only those fields that match the field names specified by
|
|
Include files in the unload depot when displaying data. See p4 unload for details. |
|
See “Global Options”.
The |
Usage Notes
Can File Arguments Use Revision Specifier? |
Can File Arguments Use Revision Range? |
Minimal Access Level Required |
---|---|---|
Yes |
Yes |
|
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.
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
"
".
The fieldname
=value
value
must be a single token, including
both alphanumeric characters and punctuation.
The wildcard "*
" allows for partial word matches. The
filter "
*"
matches "fieldname
=stringstring
", "stringy
",
"stringlike
", and so on.
Date fields can be matched by expressing the filter date as
or yyyy
/mm
/dd
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
.
Other Usage Notes
-
If you use
-e
with thechangelist
-Ro
option, only pending changes are considered, so that files open for add are included in the output. -
For files containing the special characters
@
,#
,*
, and%
, theclientFile
displays the special character, and thedepotFile
displays the filename containing the ASCII expression of the character's hexadecimal value. -
The
size
anddigest
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. -
The
-L
option is intended for use by scripts or automated reporting processes. File arguments must be in full depot syntax, and have a valid revision number. File specifications that do not meet these requirements are silently ignored. -
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.
Examples
p4 fstat file.c |
Displays information on |
p4 fstat //....c@20,@now |
Displays information on all |
p4 fstat -Os file.c |
No client workspace information lines
( |
p4 fstat -Osl file.c |
No client workspace information lines are displayed, but the
|
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 |
p4 fstat -Ol -F "fileSize < 1024 & headType=text" //depot/main/... |
Display information on all text files under
|
p4 fstat -T 'depotFile, headRev' file.c |
Display only the |