p4 fstat

Dump file information in a tagged format that is 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] FileSpec[revRange] ...
p4 [g-opts] fstat [-F filter -T fields -m max -r] [-c|-e change]  
                  [-Ox -Rx -Sx] [-A pattern] [--streamviews] FileSpec[revRange] ...

where x represents the second letter in an option such as -On

Syntax conventions

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 Helix C/C++ API application, where the items can be accessed as variables, but the output is also suitable for parsing by scripts.

The only argument required for the p4 fstat command is the FileSpec argument.

The p4 fstat command has options to limit the set of files operated on and to determine how information is displayed.

• 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 limit the output to the first max files, use the -m max option.
• To filter the output of the form fields, use the -F filter option. For example, all files larger than a certain size and with a certain filetype An attribute that determines how the server stores and diffs a particular file. Examples of file types are text and binary..
• 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. See also the Timestamp and Unix epoch time information.

Form Fields

The fields shown vary depending on which file is selected.

... otherOpen 3
...... otherOpen0 user1@ws1
...... otherOpen1 user2@ws2
...... otherOpen2 user3@ws3

Options

Usage Notes

Filter with -F

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 Helix Server "..." 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

Examples for attributes

To display the attributes of a specified file

The p4 fstat -Oa command shows the values of attributes. To learn about attributes, see p4 attribute.

Look for the attr- prefix:

$ p4 fstat -Oa //depot/main/release1/perl_proj/kitten.gif
... depotFile //depot/main/release1/perl_proj/kitten.gif
... clientFile /home/bruno/main/release1/perl_proj/kitten.gif
... isMapped
... headAction edit
... headType text
... headTime 1422908282
... headRev 4
... headChange 25424
... headModTime 1422908084
... attr-black-and-white true

To search for an attribute across a set of files

To display the attributes with their values, include the -F option of p4 fstat to find files with specific attributes.

$ p4 fstat -Oa -F "attr-black-and-white=true" "attr-preview" //depot/main/release1/perl_proj/...
... depotFile //depot/main/release1/perl_proj/kitten.gif
... clientFile /home/bruno/main/release1/perl_proj/kitten.gif
... isMapped
... headAction edit
... headType text
... headTime 1422908282
... headRev 4
... headChange 25424
... headModTime 1422908084
... attr-black-and-white true

To display the storage location of attributes

The -On option shows the storage location of attributes rather than their values. In this example, the value of the black-and-white and size traits are stored in the db.traits table, but the value of the preview trait is stored in the trait depot, which is represented as .p4traits:

$ p4 fstat -On //depot/main/release1/perl_proj/...
... depotFile //depot/main/release1/perl_proj/kitten.gif
... clientFile /home/bruno/main/release1/perl_proj/kitten.gif
... isMapped
... headAction edit
... headType text
... headTime 1422908282
... headRev 4
... headChange 25424
... headModTime 1422908084
... attr-black-and-white db.traits
... attr-size db.traits
... attr-preview .p4traits

Related Commands