File specifications
Any file can be specified within any Helix Server command in client syntax, depot syntax, or local syntax. Workspace names and depot names share the same namespace. The Helix Core 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.)
Helix 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 Helix Server syntax.
Helix 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 |
|---|---|
|
Local syntax |
/staff/bruno/myworkspace/file.c for Linux c:\staff\bruno\myworkspace\file.c for Windows |
|
Depot syntax |
|
|
Client syntax |
|
Wildcards
The Helix 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. |
|
|
Positional specifiers for substring rearrangement in filenames, when used in views. |
Examples of wildcard expressions:
| Expression | Matches | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Files in the current directory starting with J |
||||||||||
|
|
All files called |
||||||||||
| //gra*/dep* | //graph/depot/, //graphs/depots, gravity/deposits but not //graph/depot/release1/ | ||||||||||
|
|
All files under the current directory and its subdirectories |
||||||||||
|
|
All files under the current directory and its subdirectories, that end in .c |
||||||||||
|
|
All files under /usr/bruno_ws |
||||||||||
|
|
All files in the depot named |
||||||||||
|
|
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
Get the latest version from the depot into the workspace:
|
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 |
|---|---|
|
|
Revision specifier: The |
|
|
The nonexistent revision: If a revision of
This is useful when you want to remove a file from the client
workspace while leaving it intact in the depot, as in The filespec |
|
|
The head revision (latest version) of |
|
|
The revision on the current client: the revision of file last synched into the
client workspace with |
|
|
Change number: The revision of |
|
|
Change number: The revision of
|
|
|
Label name: The revision of |
|
|
Client name: The revision of Note that deleted files (that is, files marked for
|
|
Date and time: The revision of If no time is specified, the head revision at 00:00:00 on the morning of the date specified is returned. Dates are specified
|
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
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 @=, where
changechange is the pending changelist number.
Some
Helix 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-Helix Server) DOS commands as an
option specifier. File names with spaces in them might 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
Helix 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 |
|---|---|
|
Revision ranges implicitly start at To see only those jobs that were fixed by
revision 5, specify
|
If the
If revision |
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 Helix Core Command-Line (P4) Guide
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 | Helix Server Usage | Not allowed for the entity you create with |
|---|---|---|
|
|
recursive subdirectory wildcard file matching wildcard positional substitution wildcard |
|
|
|
separating pathname components |
and not allowed in the name of a file |
|
|
No special meaning for Helix 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. |
|
|
|
specifying the revision number |
|
|
|
changelist numbers are purely numeric |
A purely numberic identifier is NOT allowed for a user, client,
depot, label, job, or stream, so consider something like
|
To refer to files containing the
Helix 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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
:
|
%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:
$ 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 Helix 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.
