File specifications

Any file can be specified within any P4 Server command in client syntax, depot syntax, or local syntax. Workspace names and depot names share the same namespace. The P4 server can distinguish a workspace name from a depot name.

Syntax forms

Local syntax refers to filenames as specified by the local shell or operating system. Filenames referred to in local syntax can be specified by their absolute paths or relative to the current working directory. (Relative path components can only appear at the beginning of a file specifier.)

P4 Server has its own method of file specification which remains unchanged across operating systems. If a file is specified relative to a client root, it is said to be in client syntax. If it is specified relative to the top of the depot, it is said to be in depot syntax. A file specified in either manner can be said to have been specified in P4 Server syntax.

P4 Server file specifiers always begin with two slashes (//), followed by the client or depot name, followed by the full pathname of the file relative to the client or depot root directory.

Path components in client and depot syntax are always separated by slashes (/), regardless of the component separator used by the local operating system or shell.

An example of each syntax:

Syntax Example

Syntax	Example
Local syntax	/staff/bruno/myworkspace/file.c for Linux c:\staff\bruno\myworkspace\file.c for Windows
Depot syntax	`//depot/source/module/file.c`
Client syntax	`//myworkspace/file.c`

Local syntax

/staff/bruno/myworkspace/file.c for Linux

c:\staff\bruno\myworkspace\file.c for Windows

Depot syntax

//depot/source/module/file.c

Client syntax

//myworkspace/file.c

Wildcards

The P4 Server system allows the use of these wildcards:

Wildcard	Meaning
`*`	Matches all characters except slashes within one directory.
`...`	Matches all files under the current working directory and all subdirectories. Matches anything, including slashes, and does so across subdirectories.
`%%1 - %%9`	Positional specifiers for substring rearrangement in filenames, when used in views.

Examples of wildcard expressions:

Expression Matches

J*

Files in the current directory starting with J

*/help

All files called help in current subdirectories

//gra*/dep* //graph/depot/, //graphs/depots, gravity/deposits but not //graph/depot/release1/

./...

All files under the current directory and its subdirectories

./....c

All files under the current directory and its subdirectories, that end in .c

/usr/bruno_ws/...

All files under /usr/bruno_ws

//companytools/...

//bruno_ws/...

All files in the depot named companytools or the workspace named bruno_ws

//depot/...

All files in the depot (with the default name of "depot")

//depot/main/rel... //depot/main/rel/, //depot/main/releases/, //depot/main/release-note.txt, //depot/main/rel1/product1 and so on

//...

All files in all depots

//depot/dir1/%%1.%%2 //bruno_ws/filesbytype/%%2/%%1

This example uses positional specifiers in client view mapping to rearrange the sync'd files by file type. The depot files with a given extension, such as .txt, are sync'd into a workspace directory that bears the extension name, such as (/txt):

For the depot,
- Specify the file name at position 1 by using %%1
- Specify the file extension at position 2 by using %%2
For the workspace,
- Reverse the order so that the extension %%2 is before the file name %%1
- Substitute a forward slash (/) of a directory for the period (.) of a file extension

Get the latest version from the depot into the workspace:

sync -f //depot/dir1/...

Depot file with extension ...	results in Workspace directory with file ...
`//depot/dir1/readme.docx`	`//bruno_ws/filesbytype/doc/readme`
`//depot/dir1/readme.md`	`/Users/bruno_ws/filesbytype/md/readme`
`//depot/dir1/readme.pl`	`/Users/bruno_ws/filesbytype/pl/readme`
`//depot/dir1/readme.txt`	`/Users/bruno_ws/filesbytype/txt/readme`

Using revision specifiers

File specifiers can be modified by appending # or @ to them.

The # and @ specifiers refer to specific revisions of files as stored in the depot:

Modifier	Meaning
`file#n`	Revision specifier: The `n`th revision of `file`.
`file#none` `file#0`	The nonexistent revision: If a revision of `file` exists in the depot, it is ignored. This is useful when you want to remove a file from the client workspace while leaving it intact in the depot, as in `p4 sync` `file#none`. The filespec `#0` can be used as a synonym for `#none` - the nonexistent revision can be thought of as the one that "existed" before the first revision was submitted to the depot.
`file#head`	The head revision (latest version) of `file`. Except where explicitly noted, this is equivalent to referring to the file without a revision specifier.
`file#have`	The revision on the current client: the revision of file last synched into the client workspace with `p4 sync`.
`file@n`	Change number: The revision of `file` immediately after changelist `n` was submitted.
`file@=n`	Change number: The revision of `file` at the specified changelist number `n`. `n` can be a submitted or a shelved change number. `n` cannot be a pending (non-shelved) change number.
`file@labelname`	Label name: The revision of `file` in the label `labelname`.
`file@clientname`	Client name: The revision of `file` last taken into client workspace `clientname`. Note that deleted files (that is, files marked for `delete` at their latest revision) are not considered to be part of a workspace.
`file@datespec`	Date and time: The revision of `file` at the date and time specified. If no time is specified, the head revision at 00:00:00 on the morning of the date specified is returned. Dates are specified `yyyy/mm/dd:hh:mm:ss` or `yyyy/mm/ddhh:mm:ss` (with either a space or a colon between the date and the time). `@now` - the datespec `@now` can be used as a synonym for the current date and time.

Revision specifiers can be used to operate on many files at once: p4 sync //myclient/...#4 copies the fourth revision of all non-open files into the client workspace.

If specifying files by date and time (that is, using specifiers of the form file@datespec), the date specification should be parsed by your local shell as a single token. You might need to use quotation marks around the date specification if you use it to specify a time as well as a date.

Files that have been shelved can also be accessed with the p4 diff, p4 diff2, p4 files, and p4 print commands, using the revision specifier @=change, where change is the pending changelist number.

Some P4 Server file specification characters might be intercepted and interpreted by the local shell, and need to be escaped before use. For instance, # is used as the comment character in most UNIX shells, and / might be interpreted by (non-P4 Server) DOS commands as an option specifier. File names with spaces in them might have to be quoted on the command line.

Using revision ranges

A few P4 Server commands can use revision ranges to modify file arguments. Revision ranges are two separate revision specifications separated by a comma. For example, p4 changesfile#3,5

Revision ranges have two separate meanings, depending on which command you’re using:

Run on all revisions in the specified range Run on the highest revision in the specified range

Run on all revisions in the specified range	Run on the highest revision in the specified range
`p4 changesfile#3,5` lists the changelists that submitted the `file` at its third, fourth, and fifth revisions. `p4 jobs //...#20,52` lists all jobs fixed by any changelist that submitted any file at its 20th through 52nd revision. Revision ranges implicitly start at `#1`, so `p4 fixes//depot/file.c#5` implies all jobs fixed by revisions 1 through 5. To see only those jobs that were fixed by revision 5, specify `p4 fixes//depot/file.c#5,5`. `p4 changesfile#3,@labelname` lists all changelists that submitted the `file` between its third revision and the revision stored in label `labelname`.	If the `file` has two revisions, `#1` and `#2`: `p4 print file#1,2` prints revision `#2` `p4 print file#1,5` prints revision `#2` `p4 print file#3,5` prints nothing If revision `#1` of the `file` was submitted in changelist 20, and revision `#2` of the `file` was submitted in changelist 60: `p4 print` file@30,50 prints nothing `p4 print` file@50 prints revision #1 of `file`
This applies to `p4 changes`, `p4 fixes`, `p4 integrate`, `p4 jobs`, and `p4 verify`	This applies to `p4 files`, `p4 print`, and `p4 sync`

p4 changesfile#3,5 lists the changelists that submitted the file at its third, fourth, and fifth revisions.

p4 jobs //...#20,52 lists all jobs fixed by any changelist that submitted any file at its 20th through 52nd revision.

Revision ranges implicitly start at #1, so p4 fixes//depot/file.c#5 implies all jobs fixed by revisions 1 through 5.

To see only those jobs that were fixed by revision 5, specify p4 fixes//depot/file.c#5,5.

p4 changesfile#3,@labelname lists all changelists that submitted the file between its third revision and the revision stored in label labelname.

If the file has two revisions, #1 and #2:

p4 print file#1,2 prints revision #2

p4 print file#1,5 prints revision #2

p4 print file#3,5 prints nothing

If revision #1 of the file was submitted in changelist 20, and revision #2 of the file was submitted in changelist 60:

p4 print file@30,50 prints nothing
p4 print file@50 prints revision #1 of file

This applies to p4 changes, p4 fixes, p4 integrate, p4 jobs, and p4 verify This applies to p4 files, p4 print, and p4 sync

The range can combine revision and changelist:

p4 print -a file#9,@2481
p4 changesfile#3,@labelname - see Labels in the P4 CLI Documentation

Limitations on characters in filenames and entities

When you name files and entities, such as users and clients, be aware of the following limitations.

Character	P4 Server Usage	Not allowed for the entity you create with
`...` `*` `%%`	Recursive subdirectory wildcard File matching wildcard Positional substitution wildcard	`p4 user`, `p4 client`, `p4 depot`, `p4 label`, `p4 job`, `p4 stream`
`/`	Separating pathname components OK for `p4 user`, `p4 label`, and `p4 job`	`p4 client`, `p4 depot` and not allowed in the name of a file.
`\`	No special meaning for P4 Server.	Allowed, but be aware that Microsoft Windows uses the backslash as the separator for pathname components.
`@`	Prefix to the identifier of a changelist, label, client, or datespec.	`p4 user`, `p4 client`, `p4 depot`, `p4 label`, `p4 job`, `p4 stream`
`#`	Specifying the revision number	`p4 user`, `p4 client`, `p4 depot`, `p4 label`, `p4 job`, `p4 stream`
`1` or `1234`	Changelist numbers are purely numeric	A purely numeric identifier is NOT allowed for a user, client, depot, label, job, or stream, so consider something like `1a` or `1_234`.

To refer to files containing the P4 Server revision specifier wildcards (@ and #), file matching wildcard (*), or positional substitution wildcard (%%) in either the file name or any directory component, use the ASCII expression of the character’s hexadecimal value. ASCII expansion applies to the following characters:

Character	ASCII expansion
`@`	`%40`
`#`	`%23`
`*`	`%2A`
`%`	`%25`
`:`	`%3A`

To add a file, such as status@june.txt, force a literal interpretation of special characters by using:

p4 add -f //depot/path/status@june.txt

When you submit the changelist, the characters are automatically expanded and appear in the change submission form as follows:

//depot/path/status%40june.txt

After submitting the changelist with the file’s addition, you must use the ASCII expansion in order to sync it to your workspace or edit it within your workspace:

Copy

p4 sync //depot/path/status%40june.txt
p4 edit //depot/path/status%40june.txt

Most special characters tend to be difficult to use in filenames in cross-platform environments: UNIX separates path components with /, while many DOS commands interpret / as a command line switch. Most UNIX shells interpret # as the beginning of a comment. Both DOS and UNIX shells automatically expand * to match multiple files, and the DOS command line uses % to refer to variables.

Similarly, although non-ASCII characters are allowed in filenames and P4 Server identifiers, entering these characters from the command line might require platform-specific solutions. Users of GUI-based file managers can manipulate such files with drag-and-drop operations.