Perforce 2000.2 Command Reference (2000.2.cr.1)
<< Previous Chapter
Global Options
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Views

File Specifications


Synopsis

Any file can be specified within any Perforce command in client syntax, depot syntax, or local syntax. Client workspace names and depot names share the same namespace; there is no way for the Perforce server to confuse a client name with 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 may be specified by their absolute paths or relative to the current working directory. (Relative path components may only appear at the beginning of a file specifier.)

Perforce 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 Perforce syntax. Perforce 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 is provided below

Syntax
Example

Local syntax

/staff/user/usercws/file.c

Depot syntax

//depot/source/module/file.c

Client syntax

//usercws/file.c

Wildcards

The Perforce system allows the use of three wildcards:

Wildcard
Meaning

*

Matches all characters except slashes within one directory.

...

Matches all files under the current working directory and all subdirectories. (i.e. matches anything, including slashes, and does so across subdirectories)

%1 - %9

Positional specifiers for substring rearrangement in filenames.

Using Revision Specifiers

File specifiers may be modified by appending # or @ to them. These are used to refer to specific revisions of files as stored in the depot:

Modifier
Meaning

file#n

Revision specifier: The nth revision of file.

file#none

The nonexistent revision: If a revision of file exists in the depot, it will be ignored. This is useful when you want to remove a file from the client workspace while leaving it intact in the depot, e.g. p4 sync file#none.

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 p4 synced into the client workspace

file@n

Change number: The revision of file immediately after changelist n was submitted.

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.

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 will be returned. Dates are specified yyyy/mm/dd:hh:mm:ss or
yyyy/mm/dd hh:mm:ss (with either a space or a colon between the date and the time).

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

Perforce filenames may not contain unprintable characters, wildcards, nor the revision-specifying characters @ and #.

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

Some of Perforce's file specification characters may be intercepted and interpreted by the local shell. These will have to be escaped before use. For instance, # is used as the comment character in most UNIX shells, / may be interpreted by (non-Perforce) DOS commands as an option specifier, and MacOS uses the : character as the separator between local path components. File names with spaces in them may have to be quoted on the command line.

For information on these and other platform-specific issues, see the release notes for your platform.

Using Revision Ranges

A few Perforce commands can use revision ranges to modify file arguments. Revision ranges are two separate revision specifications, separated by a comma. For example, p4 changes foo#3,5 will list the changelists that submitted file foo at its third, fourth, and fifth revisions.

Revision ranges have two separate meanings, depending on which command you're using. The two meanings are:

This interpretation of revision ranges applies to p4 changes, p4 fixes, p4 integrate, p4 jobs, and p4 verify.

The commands p4 files, p4 print, and p4 sync all use revision ranges in this fashion.

Revision ranges can be very powerful. For example, p4 changes foo#3,@labelname will list all changelists that submitted file foo between its third revision and the revision stored in label labelname.

Illegal characters

Because of Perforce's naming conventions, certain characters cannot be used in file names, nor may they appear in the names of clients, labels, etc. These include unprintable characters, the above wildcards, and the Perforce revision characters @ and #.

The following characters cannot be used in file names:

Character
Reason

@

Perforce revision specifier for date, label name, or changelist number.

#

Perforce revision specifier for revision numbers.

*

Perforce wildcard: matches anything, works within a single directory

...

Perforce wildcard: matches anything, works at the current directory level and includes files in all directory levels below the current level.

%

Perforce wildcard: %0 through %9 are used for positional substitutions.

/

Perforce separator for pathname components.

Observe that most of these 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.


Perforce 2000.2 Command Reference (2000.2.cr.1)
<< Previous Chapter
Global Options
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Views
Please send comments and questions about this manual to [email protected].
Copyright 1997, 2000 Perforce Software. All rights reserved.
Last updated: 12/21/00