Previous Table of Contents Index Next
Perforce 2009.2: P4 User's Guide



Chapter 3
This chapter provides basic information about p4 commands, including command-line syntax, arguments, and flags. For full details about command syntax, refer to the Perforce Command Reference.
Certain commands require administrator or superuser permission. For details, consult the Perforce System Administrator's Guide
Command-line syntax
The basic syntax for commands is as follows:
p4 [global options] command [command-specific flags] [command arguments]
The following flags can be used with all p4 commands.
-c clientname
-d directory
-H host
-p server
-P password
Supplies a Perforce password, overriding P4PASSWD. Usually used in combination with the -u username flag.
-u username
-x filename
Read arguments, one per line, from the specified file. To read arguments from standard input, specify "-x -".
To display the flags for a specific command, issue the p4 help command. For example:
    add -- Open a new file to add it to the depot
    p4 add [ -c changelist# ] [ -t filetype ] file ...
        Open a new file for adding to the depot. If the file exists
        on the client it is read to determine if it is text or binary.
        If it does not exist it is assumed to be text. The file must
        either not exist in the depot, or it must be deleted at the
        current head revision. Files may be deleted and re-added.
[...]
For the full list of global options, commands, and command-specific flags, see the Perforce Command Reference.
Specifying filenames on the command line
Much of your everyday use of Perforce consists of managing files. You can specify filenames in p4 commands as follows:
Local syntax: the file's name as specified in your local shell or operating system.
Filenames can be specified using an absolute path (for example, c:\bruno_ws\dev\main\jam\fileos2.c) or a path that is relative to the current directory (for example, .\jam\fileos2.c).
Relative components (. or ..) cannot be specified following fixed components. For example, mysub/mydir/./here/file.c is invalid, because the dot (.) follows the fixed mysub/mydir components.
Depot syntax: use the following format: //depotname/file_path, specifying the pathname of the file relative to the depot root directory. Separate the components of the path using forward slashes. For example: //depot/dev/main/jam/Jambase.
Client syntax: use the following format: //workspacename/file_path, specifying the pathname of the file relative to the client root directory. Separate the components of the path using forward slashes. For example: //ona-agave/dev/main/jam/Jambase.
Example: Using different syntaxes to refer to the same file
Local syntax: p4 delete c:\bruno_ws\dev\main\jam\Jambase
Depot syntax: p4 delete //depot/dev/main/jam/Jambase
Client syntax: p4 delete //bruno_ws/dev/main/jam/Jambase
Perforce wildcards
For commands that operate on sets of files, Perforce supports two wildcards.
Matches anything except slashes. Matches only within a single directory. Case sensitivity depends on your server platform
Matches anything including slashes. Matches recursively (everything in and below the specified directory).
Perforce wildcards can be used with local or Perforce syntax, as in the following examples.
All files called help in current subdirectories
The * wildcard is expanded locally by the operating system before the command is sent to the server. To prevent the local operating system from expanding the * wildcard, enclose it in quotes or precede it with a backslash.
The "..." wildcard cannot be used with the p4 add command. The "..." wildcard is expanded by the Perforce server, and, because the server cannot determine which files are being added, it can't expand the wildcard. The * wildcard can be used with p4 add, because it is expanded by the operating system shell and not by the Perforce Server.
Restrictions on filenames and identifiers
Spaces in filenames, pathnames, and identifiers
Use quotation marks to enclose files or directories that contain spaces. For example:
"//depot/dev/main/docs/manuals/recommended configuration.doc"
If you specify spaces in names for other Perforce objects, such as branch names, client names, label names, and so on, the spaces are automatically converted to underscores by the Perforce server.
Length limitations
Names assigned to Perforce objects such as branches, client workspaces, and so on, cannot exceed 1024 characters.
Reserved characters
By default, the following reserved characters are not allowed in Perforce identifiers or names of files managed by Perforce.
These characters have conflicting and secondary uses. Conflicts include the following:
UNIX separates path components with /, but 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.
To specify these characters in filenames or paths, use the ASCII expression of the character's hexadecimal value, as shown in the following table.
Specify the filename literally when you add it; then use the ASCII expansion to refer to it thereafter. For example, to add a file called [email protected], issue the following command:
p4 add -f //depot/dev/main/docs/manuals/[email protected]
When you submit the changelist, the characters are automatically expanded and appear in the change submission form as follows:
//depot/dev/main/docs/manuals/recommended%40configuration.doc
After you submit the changelist with the file's addition, you must use the ASCII expansion to sync the file to your workspace or to edit it within your workspace. For example:
p4 sync //depot/dev/main/docs/manuals/recommended%40configuration.doc
Filenames containing extended (non-ASCII) characters
Non-ASCII characters are allowed in filenames and Perforce identifiers, but entering them from the command line might require platform-specific solutions. If you are using Perforce in unicode mode, all users must have P4CHARSET set properly. For details about setting P4CHARSET, see the Perforce Command Reference and the Internationalization Notes.
In international environments, use a common code page or locale setting to ensure that all filenames are displayed consistently across all machines in your organization. To set the code page or locale:
Windows: use the Regional Settings applet in the Control Panel
UNIX: set the LOCALE environment variable
Specifying file revisions
Each time you submit a file to the depot, its revision number is incremented. To specify revisions prior to the most recent, use the # revision specifier to specify a revision number, or @ to specify a date, changelist, client workspace, or label corresponding to the version of the file you are working on. Revision specifications can be used to limit the effect of a command to specified file revisions.
Some operating system shells treat the Perforce revision character # as a comment character if it starts a word. If your shell is one of these, escape the # when you use it in p4 commands.
The following table describes the various ways you can specify file revisions.
The revision submitted as of a specified changelist
file@changelist_number
Refers to the version of Jambase when changelist 126 was submitted, even if it was not part of the change.
The revision in a specified label
file@labelname
The revision of Jambase in the label called beta. For details about labels, refer to Using labels.
The revision last synced to a specified client workspace
file@clientname
The revision of Jambase last synced to client workspace bruno_ws
file#none
Removes Jambase from the client workspace.
file#head
Same as p4 sync //depot/dev/main/jam/Jambase
The revision last synced to your workspace
file#have
The head revision of the file in the depot on the specified date
file@date
The head revision of Jambase as of midnight May 18, 2005.
The head revision of the file in the depot on the specified date at the specified time
file@"date[:time]"
Specify dates in the format YYYY/MM/DD. Specify time in the format HH:MM:SS using the 24-hour clock. Time defaults to 00:00:00
Separate the date and the time by a single space or a colon. (If you use a space to separate the date and time, you must also enclose the entire date-time specification in double quotes.)
Example: Retrieving files using revision specifiers
Bruno wants to retrieve all revisions that existed at changelist number 30. He types
p4 sync //depot/dev/main/jam/[email protected]
Another user can sync their workspace so that it contains the same file revisions Bruno has synced by specifying Bruno's workspace, as follows:
p4 sync @bruno_ws
Example: Removing all files from the client workspace
p4 sync ...#none
The files are removed from the workspace but not from the depot.
Date and time specifications
Date and time specifications are obtained from the time zone of the Perforce server. To display the date, time, offset from GMT, and time zone in effect at your Perforce server, issue the p4 info command. The Perforce server stores times as the number of seconds since 00:00:00 GMT Jan. 1, 1970), so if you move your server across time zones, the times stored on the server are correctly reported in the new time zone.
Revision ranges
Some commands can operate on a range of file revisions. To specify a revision range, specify the start and end revisions separated by a comma, for example, #3,4.
The commands that accept revision range specifications are:
For the preceding commands:
If you specify a single revision, the command operates on revision #1 through the revision you specify (except for p4 sync, p4 print, and p4 files, which operate on the highest revision in the range).
Example: Listing changes using revision ranges
A release manager needs to see a quick list of all changes made to the jam project in July 2000. He types:
p4 changes //depot/dev/main/jam/[email protected]/7/1,2000/8/1
The resulting list of changes looks like this:
Change 673 on 2000/07/31 by [email protected]_ws 'Final build for QA'
Change 633 on 2000/07/1 by [email protected]_ws 'First build w/bug fix'
Change 632 on 2000/07/1 by [email protected]_ws 'Started work'
Reporting commands
The following table lists some useful reporting commands.
A list of p4 commands with a brief description
p4 help command
Preview the results of a p4 sync (to see which files would be transferred)
Preview the results of a p4 delete (to see which files would be marked for deletion)
Using Perforce forms
Some Perforce commands, for example p4 client and p4 submit, use a text editor to display a form into which you enter the information that is required to complete the command (for example, a description of the changes you are submitting). After you change the form, save it, and exit the editor, Perforce parses the form and uses it to complete the command. (To configure the text editor that is used to display and edit Perforce forms, set P4EDITOR.)
When you enter information into a Perforce form, observe the following rules:
Field names (for example, View:) must be flush left (not indented) and must end with a colon.
Some field names, such as the Client: field in the p4 client form, require a single value; other fields, such as Description:, take a block of text; and others, like View:, take a list of lines.
Certain values, like Client: in the client workspace form, cannot be changed. Other fields, like Description: in p4 submit, must be changed. If you don't change a field that needs to be changed, or vice versa, Perforce displays an error. For details about which fields can be modified, see the Perforce Command Reference or use p4 help command.


Previous Table of Contents Index Next

Perforce 2009.2: P4 User's Guide
Copyright 2005-2009 Perforce Software.