Syntax and naming conventions

Syntax conventions

Notation Meaning Syntax Example command
literal Must be used in the command exactly as shown. p4 revert -So p4 revert -So
italics A parameter you must provide specific information for. p4 user -d username p4 user -d msmith 
-a -b or --a --b
 Both elements are required. p4 renameuser --from=old --to=new p4 rename msmith mjones
[-a -b] Any combination of the enclosed elements is allowed and none of the elements are required. Omit the brackets when entering the command. p4 delete [-n -k -v] file ... p4 delete readme.txt 
[-a | -b]
 Exactly one of the enclosed elements is allowed and none of the elements are required. Omit the brackets when entering the command. p4 group [-a | -A] groupname p4 group admins 
{-a | -b}
 Exactly one of the enclosed elements is required. Omit the curly braces when entering the command. p4 bgtask {-e command | -t triggerName}
p4 bgtask -t fileSizeCheckTrigger
... Previous argument can be repeated. ... has a different meaning for directories. See Wildcards under File specifications. p4 [g-opts] streamlog [ -l -L -t -m max ] stream1 ... p4 streamlog //project1/s1 //project1/s2

Naming conventions

  • Clients, depots, labels, and branches cannot share the same name.
  • The following names are reserved and cannot be used to name anything: head, have, none.

The following table provides some suggestions:

Object Naming convention

branches

Best to name them.

clients

The following scheme is commonly used, but not enforced in any way. Use it if it suits your purpose.

user.machineTag.product

user.machineTag.product.branch

user is the OS user. machineTag is the host name or something that describes the host, for example Win7VM or P4MBPro (for MacBook Pro).

Whether you use product or product.branch depends on whether your workspace gets re-purposed from stream to stream, in which case use product), or you have multiple workspaces, one for each branch, in which case use product.branch to tie the workspace name to the branch.

depots

Best to keep the names short.

Depot names are part of an organization hierarchy for all your digital assets, so naming them and planning directory structure is especially important.

jobs

Name jobs to match your external defect tracker issues: for example, PRJ-1234 for Jira issues.

labels

Label names are site-dependent and might vary with code management schemes and versioning needs. For example R-3.2.0 might refer to release 3.2.0.

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 P4 Server objects, such as branch names, client names, label names, and so on, the spaces are automatically converted to underscores by the P4 Server.

Length limitations

Names assigned to P4 Server 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 P4 Server identifiers or names of files managed by P4 Server:

Reserved Character Reason

@

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

#

File revision numbers

*

Wildcard

...

Wildcard (recursive)

%%1 - %%9

Wildcard (see Rearrange parts of filenames with positional specifiers)

/

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 P4 Server identifiers, but entering them from the command line might require platform-specific solutions. If you are using P4 Server in Unicode mode, all users must have the P4CHARSET environment variable set properly. See also 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