Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Reference | 2025.1

# 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 P4 API for C/C++ 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 `-S`x`` 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: binary, text, and unicode..
- 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.

Field Name | Description | Example/Notes
--- | --- | ---
`attr-`name`` | Attribute value with the `-Oa` option. In some cases the value might be huge. Attribute location with the `-On` option. The location might be the `db.traits` table, or the `.p4traits` depot for huge attributes. | `attr-myAttr critical` or `attr-preview`
`attrProp-`name`` | Set if `attr-`name`` is a propagating attribute. | `attrProp-myAttr`
`clientFile` | Local path to file in local syntax by default, or in P4 Server 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 P4 Server 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`
`isMissing` | Set if the rev is known to not be in the depot. |
`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, which is 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 the workspace, if it is on the workspace. | `23`
`desc` | Changelist description if using `-e changelist` and if the file was part of `changelist` | A P4 Server changelist
`digest` | MD5 digest of a file. This requires the `-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. This requires the `-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 P4 Server file type
`charset` | Open charset | (for unicode files)
`actionOwner` | User who opened the file, if open. | A P4 Server 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`
`lockOnCommit` | Set if locked on commit server |
`otherLockGlobal` | Set if lock is global |
`otherLockGlobal#` | user@client with file globally locked |
`otherLockOnCommit` | Set if locked on commit server |
`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 `otherOpen`n``, `otherAction`n``, and `otherLock`n`` fields as applicable. For example:
    ... otherOpen 3
    ...... otherOpen0 user1@ws1
    ...... otherOpen1 user2@ws2
    ...... otherOpen2 user3@ws3
`otherOpen`n`` | 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`
`otherLock`n`` | For each user with the file locked, the workspace and user holding the lock | `user123@workstation9` Only one user at a time can lock a file with `p4 lock`, but the output of `p4 fstat` differs depending on the user that runs the command and the workspace in which they run the command. A lock held by the current user and workspace is recorded as `ourLock`, and, if `n` is set, `n` is `0`. A lock held by a different user or workspace appears as one of the `other` events, such as `otherOpen0`, `otherAction0`, `otherChange0`, or `otherLock0`. For each additional user there is a different integer.
`otherAction`n`` | 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`.
`otherChange`n`` | 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` | If the lock is held by the current user and workspace, the lock is recorded as `ourLock`. If the lock is held by a different user and/or workspace the lock is recorded as one of the `other` events. | `ourLock`
`resolveAction`n`` `resolveBaseFile`n`` `resolveBaseRev`n`` `resolveFromFile`n`` `resolveStartFromRev`n`` `resolveEndFromRev`n`` | Pending integration action, base file, base revision number, from file, starting, and ending revision, respectively. | For pending integration record information, use the `-Or` option.
`revtime` | If opened in your workspace, the file modification time, if the file is shelved. |
`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 `-S`x`` or `-r` sorting options.

## Options

Option | Description
--- | ---
`-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 modified by the specified changelist or after that changelist was submitted. 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 Filter with -F. Filtering is not optimized with indexes for performance.
`-L` | Use with a list of file arguments in full depot syntax with a valid revision number for fast processing of the list.
`-m max` | Produce fstat output for only the first `max` files.
`-Oa` | Fetch and display the attribute values set by the `p4 attribute` command. Each attribute value is fetched from its storage location, which is either the trait depot or the `db.traits` table. Attributes fetched from the trait depot might impact performance. See also the `-On` option.
`-Ob` | Output the path, revision, type, full and relative local paths of the server archive file. Requires admin privilege.
`-Od` | Output the MD5 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 an MD5 digest field for each revision. p4 fstat -e shelvedChange -Rs -Ol reports the file size and MD5 digest of files shelved at the specified change. This might be expensive to compute.
`-Om` | Output includes other ditto mapped client files. See "ditto mapping" in Client Views.
`-On` | Display each attribute with its trait value storage location, the `db.traits` table or the trait depot (`.p4traits`), instead of the value, which is available with the `-Oa` option. For an example with the `-On` option, see To display the storage location of attributes and the p4 attribute topic.
`-Op` | Output the `clientFile` path in both: Depot syntax The syntax for specifying the location of files in the P4 Server depot as opposed to in the user's client workspace. Depot syntax begins with //depotName/, such as `//depot/readme.txt` Local syntax The way of indicating the location of files that, unlike 'depot syntax', is specific to the local operating system. This syntax is used as the second part of the client workspace mapping, after the depot syntax. Examples: /staff/maria/myworkspace/file.c for Linux and c:\staff\maria\myworkspace\file.c for Windows., that is, host form, such as `path C:\Users\maria\workspace\depot\readme.txt`
`-Or` | Output the pending integration record data for files open in the current workspace.
`-Os` | Shorten output by excluding client workspace data (for instance, the `clientFile` field).
`-OL` | When run against an edge server, output any global lock. This allows the display of global locks that would prevent a submit without the user having to query the commit server directly. This is for global locks created through p4 lock, not `+l`, which is one of the File type modifiers.
`-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 The list of file revisions most recently synced from the depot into the workspace. In other words, the list of files that the client workspace has..
`-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 MD5 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.
`--streamviews` | Report files and directories from stream Paths and Components, where imported files are represented as symbolic links under the stream depot path. If the path comes from an import or a component view, the path permissions are printed as `readonly` or `writable`, where `readonly` allows the file be opened for edit, but changes cannot be submitted, and `writable` allows both edit and submit. If the path comes from a component view, the `effectiveComponentType` is printed, where the effective component type is the most restrictive component type in a chain of components. From most restrictive to least restrictive are `readonly`, `writeimport+`, and `writeall` See the Viewing imported files example under Stream Components in the P4 CLI Documentation.
`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`

### 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 P4 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

`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 `MD5 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`.
`p4 fstat -On -F attr-preview //depot/main/rel1/perl_proj/..`. | Display the storage location of image previews in the Perl project to indicate whether the location is in the `db.trait` table or the `trait` depot.

### 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:

This command:

p4 fstat -Oa //depot/main/release1/perl_proj/kitten.gif

might output:

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

This command:

p4 fstat -Oa -F "attr-black-and-white=true" "attr-preview" //depot/main/release1/perl_proj/...

might output:

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

This command:

p4 fstat -On //depot/main/release1/perl_proj/...

might output:

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

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

Your search for returned results