Helix command syntax

This appendix provides basic information about p4 commands, including command-line syntax, arguments, and options. For full details about command syntax, refer to the P4 Command Reference.

Certain commands require administrator or superuser permission. For details, consult the Helix Versioning Engine Administrator Guide: Fundamentals.

You have the option of applying aliases to personal server commands, to do such things as:

  • abbreviation
  • creating more complex commands
  • automating simple multi-command sequences
  • providing alternate syntax for difficult-to-remember commands

For more information, see the " Introduction" chapter of P4 Command Reference.

Command-line syntax

The basic syntax for commands is as follows:

p4 [global options] command [command-specific options] [command arguments]

The following options can be used with all p4 commands:

Global options Description and Example

-c clientname

Specifies the client workspace associated with the command. Overrides P4CLIENT. 

$ p4 -c bruno_ws edit //JamCode/dev/jam/Jambase

-C charset

Specifies the client workspace’s character set. Overrides P4CHARSET. 

$ p4 -C utf8 sync

-d directory

Specifies the current directory, overriding the environment variable PWD. 

C:\bruno_ws> p4 -d c:\bruno_ws\dev\main\jam\Jambase Jamfile

-G

Format all output as marshaled Python dictionary objects (for scripting with Python). 

$ p4 -G info

-H host

Specifies the hostname of the client computer, overriding P4HOST. 

$ p4 -H deneb print //JamCode/dev/jam/Jambase

-I

Specify that progress indicators, if available, are desired. This option is not compatible with the -s and -G options.

At present, the progress indicator is only supported by two commands: submitting a changelist with p4 -I submit and “quietly” syncing files with p4 -I sync -q.

-L language

Specifies the language to use for error messages from the Helix server. Overrides P4LANGUAGE. In order for this option to work, your administrator must have loaded support for non-English messages in the database. 

$ p4 -L language info

-p port

Specifies the protocol, host and port number used to connect to the Helix service, overriding P4PORT. 

$ p4 -p ssl:deneb:1818 clients

-P password

Supplies a Helix password, overriding P4PASSWD. Usually used in combination with the -u username option. 

$ p4 -u earl -P secretpassword job

-r retries

Specifies the number of times to retry a command (notably, p4 sync) if the network times out.

-Q charset

Specifies the character set to use for command input and output; if you have set P4CHARSET to a UTF-16 or UTF-32 value, you must set P4COMMANDCHARSET to a non-UTF-16 or -32 value in order to use the p4 command-line client. 

$ p4 -Q utf32 -C utf8 sync

-s

Prepend a tag to each line of output (for scripting purposes).

$ p4 -s info

-u username

Specifies a Helix user, overriding P4USER. 

$ p4 -u bill user

-x filename

Read arguments, one per line, from the specified file. To read arguments from standard input, specify -x -. 

$ p4 -x myargs.txt

-z tag

To facilitate scripting, displays the output of reporting commands in the format as that generated by p4 fstat. 

$ p4 -z tag info

-q

Quiet mode; suppress all informational message and report only warnings or errors.

-V

Displays the version of the p4 executable.

To display the options for a specific command, issue the p4 help command. For example: 

$ p4 help add

    add -- Open a new file to add it to the depot

    p4 add [ -c changelist# ] [ -d -f -I -n ] [ -t filetype ] file ...

     Open a 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.  To be added, the file must not
     already reside in the depot, or it must be deleted at the current
     head revision.  Files can be deleted and re-added.
[...]

For the full list of global options, commands, and command-specific options, see the P4 Command Reference.

Specifying filenames on the command line

Much of your everyday use of Helix 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: //JamCode/dev/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 46. Using different syntaxes to refer to the same file

Local syntax: 

C:\bruno_ws> p4 delete c:\bruno_ws\dev\main\jam\Jambase

Depot syntax: 

C:\bruno_ws> p4 delete //JamCode/dev/jam/Jambase

Client syntax: 

C:\bruno_ws> p4 delete //bruno_ws/dev/main/jam/Jambase

Helix wildcards

For commands that operate on sets of files, Helix supports two wildcards.

Wildcard Description

*

Matches anything except slashes. Matches only within a single directory. Case sensitivity depends on your platform.

...

Matches anything including slashes. Matches recursively (everything in and below the specified directory).

Helix wildcards can be used with local or Helix syntax, as in the following examples:

Expression Matches

J*

Files in the current directory starting with J.

*/help

All files called help in current subdirectories.

./...

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

All files under /usr/bruno.

//bruno_ws/...

All files in the workspace or depot that is named bruno_ws.

//depot/...

All files in the depot named depot.

//...

All files in all depots.

The * wildcard is expanded locally by the operating system before the command is sent to the Helix server. To prevent the local operating system from expanding the * wildcard, enclose it in quotes or precede it with a backslash.

Note

The ... wildcard cannot be used with the p4 add command. The ... wildcard is expanded by the Helix server, and, because the service 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 Helix.

Restrictions on filenames and identifiers

Spaces in filenames, pathnames, and identifiers

Use quotation marks to enclose files or directories that contain spaces. For example:

"//Acme/dev/docs/manuals/recommended configuration.doc"

If you specify spaces in names for other Helix objects, such as branch names, client names, label names, and so on, the spaces are automatically converted to underscores by the Helix server.

Length limitations

Names assigned to Helix objects such as branches, client workspaces, and so on, cannot exceed 1,024 characters.

Reserved characters

By default, the following reserved characters are not allowed in Helix identifiers or names of files managed by Helix:

Reserved Character Reason

@

File revision specifier for date, label name, or changelist number

#

File revision numbers

*

Wildcard

...

Wildcard (recursive)

%%1 - %%9

Wildcard (positional)

/

Separator for pathname components

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:

Character ASCII

@

%40

#

%23

*

%2A

%

%25

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 recommended@configuration.doc, issue the following command: 

$ p4 add -f //Acme/dev/docs/manuals/recommended@configuration.doc

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

//Acme/dev/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 //Acme/dev/docs/manuals/recommended%40configuration.doc

The requirement to escape the special characters @, #, *, or % also applies if you attempt to use them in the Root: or AltRoots: fields of your client specification; escape them with %40, %23, %2A, or %25 respectively.

Filenames containing extended (non-ASCII) characters

Non-ASCII characters are allowed in filenames and Helix identifiers, but entering them from the command line might require platform-specific solutions. If you are using Helix in Unicode mode, all users must have P4CHARSET set properly. For details about setting P4CHARSET, see the P4 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 computers 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.

Warning

Some operating system shells treat the Helix 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:

Revision needed Syntax and example

Revision number

file#n

$ p4 sync //JamCode/dev/jam/Jambase#3

Refers to revision 3 of file Jambase

The revision submitted as of a specified changelist

file@changelist_number

$ p4 sync //JamCode/dev/jam/Jambase@126

Refers to the version of Jambase when changelist 126 was submitted, even if it was not part of the change. 

$ p4 sync //JamCode/dev/...@126

Refers to the state of the entire depot at changelist 126 (numbered changelists are explained in Submit a numbered changelist.

The revision in a specified label

file@label_name

$ p4 sync //JamCode/dev/jam/Jambase@beta

The revision of Jambase in the label called beta. For details about labels, refer to “Labels”.

The revision last synced to a specified client workspace

file@client_name

$ p4 sync //JamCode/dev/jam/Jambase@bruno_ws

The revision of Jambase last synced to client workspace bruno_ws.

Remove the file

file#none

$ p4 sync //JamCode/dev/jam/Jambase#none

Removes Jambase from the client workspace.

The most recent version of the file

file#head

$ p4 sync //JamCode/dev/jam/Jambase#head

Same as p4 sync //JamCode/dev/jam/Jambase

(If you omit the revision specifier, the head revision is synced.)

The revision last synced to your workspace

file#have

$ p4 files //JamCode/dev/jam/Jambase#have

The head revision of the file in the depot on the specified date

file@date

$ p4 sync //JamCode/dev/jam/Jambase@2011/05/18

The head revision of Jambase as of midnight May 18, 2011.

The head revision of the file in the depot on the specified date at the specified time

file@"date[:time]"

$ p4 sync //JamCode/dev/jam/Jambase@"2011/05/18"

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 47. Retrieving files using revision specifiers

Bruno wants to retrieve all revisions that existed at changelist number 30. He types: 

$ p4 sync //JamCode/dev/jam/Jambase@30

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 48. 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 computer that hosts the Helix server. To display the date, time, offset from GMT, and time zone in effect, issue the p4 info command. The versioning service stores times as the number of seconds since 00:00:00 GMT Jan. 1, 1970), so if you move across time zones, the times stored in the service 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:

p4 annotate
p4 changes
p4 dirs
p4 filelog
 
p4 files
p4 fixes
p4 grep
p4 integrate
 
p4 interchanges
p4 jobs
p4 labels
p4 labelsync
 
p4 list
p4 merge
p4 print
p4 sizes
 
p4 sync
p4 tag

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).
  • If you omit the revision range entirely, the command affects all file revisions.

Example 49. Listing changes using revision ranges

A release manager needs to see a quick list of all changes made to the jam project in July 2010. He types: 

$ p4 changes //JamCode/dev/jam/...@2010/7/1,2010/8/1

The resulting list of changes looks like this:

Change 673 on 2010/07/31 by bruno@bruno_ws 'Final build for QA'
Change 633 on 2010/07/1 by bruno@bruno_ws 'First build w/bug fix'
Change 632 on 2010/07/1 by bruno@bruno_ws 'Started work'

Reporting commands

The following table lists some useful reporting commands:

To display Use this command

A list of p4 commands with a brief description

p4 help commands

Detailed help about a specific command

p4 help command

Command line options common to all Helix commands

p4 help usage

Details about Helix view syntax

p4 help views

All the arguments that can be specified for the p4 help command

p4 help

The Helix settings configured for your environment

p4 info

The file revisions in the client workspace

p4 have

Preview the results of a p4 sync (to see which files would be transferred)

p4 sync -n

Preview the results of a p4 delete (to see which files would be marked for deletion)

p4 delete -n files

Using Helix forms

Some Helix 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, Helix parses the form and uses it to complete the command. (To configure the text editor that is used to display and edit Helix forms, set P4EDITOR.)

When you enter information into a Helix form, observe the following rules:

  • Field names (for example, View:) must be flush left (not indented) and must end with a colon.
  • Values (your entries) must be on the same line as the field name, or indented with tabs on the lines beneath the field name.

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, Helix displays an error. For details about which fields can be modified, see the P4 Command Reference or use p4 help command.