Perforce 2005.1 User's Guide
<< Previous Chapter
Perforce Basics:
Quick Start

Table of Contents
Index
Perforce on the Web
Next Chapter >>
Perforce Basics:
Resolving File Conflicts


Chapter 4
Perforce Basics:
The Details

This chapter covers the Perforce rules in detail. The topics discussed include views, mapping depots to client workspaces, Perforce wildcards, rules for referring to older file revisions, file types, and form syntax. For a brief overview of Perforce, see Chapter 3, Perforce Basics: Quick Start.

What is a Client Workspace?

A Perforce client workspace is a collection of files on a user's workstation that are managed by a Perforce client program. You can have more than one Perforce client workspace per workstation. The Perforce server tracks the state of all client workspaces owned by all users, including what files are on which users' workspaces and which users are working on which files.

Every client workspace on every user's workstation has a unique name that identifies the workspace to the Perforce server. If you do not specify a name for your client workspace, the name defaults to your workstation's name. You can override the default value by setting the P4CLIENT environment variable.

All files within a client workspace share a common root directory called the client workspace root. The client workspace root is the highest-level directory on your workspace under which the managed source files reside. Files under your client workspace root that are not managed by Perforce are ignored by Perforce client programs, enabling you to use Perforce to manage the source files in your client workspace while ignoring non-versioned files such as compiled object files and other temporary files created by your development tools.

Perforce client programs manage versioned files in your client workspace in three ways:

It's possible to circumvent Perforce by manually altering permissions on files in your workspace, but using Perforce is easier than circumventing it. For instance, if you need to make a temporary change to a file in your workspace, it is easier to use Perforce to open the file for edit, make your change, and then use p4 revert to discard your change, rather than to manually override file permissions or copy and restore the file.

To avoid confusion caused by inadvertent changes to workspace files, Perforce client programs include commands to verify that the state of your client workspace matches the Perforce server's record of your workspace state.

Mapping Depot files to your Client Workspace

The Perforce server manages the depot - the central repository containing every revision of every file under Perforce control. Depot files are stored in folder hierarchies, rather like those on a large hard drive.

To control where depot files appear under your client workspace root, you must map the files and directories on the Perforce server to the corresponding areas of your client workspace. These mappings constitute your client workspace view.

Setting up a client workspace view doesn't transfer any files from the server to your computer. The view only sets up the mapping that controls the relationship between the depot and your client workspace when files are transferred.

You configure your client workspace view with p4 client command. When you use the p4 client command, Perforce displays a form similar to this one:

Client: eds_elm
Owner:  edk
Description:
         Created by ed.
Root:   /usr/edk/elm
Options:        nomodtime noclobber
View:
        //depot/...   //eds_elm/...

The contents of the View: field determine where files in the depot appear on your workstation when you use p4 sync to synchronize your workspace, and where files in your client workspace are stored in the depot when you use p4 submit to update the depot with your changes.

Note

The p4 client form has more fields than those described here. For a complete list, see the Perforce Command Reference.

Client workspace views

Views consist of multiple lines, or mappings, and each mapping has two parts. The left-hand side specifies one or more files or directories in the depot, and has the form:

The right-hand side of each mapping specifies one or more files or directories in a client workspace, and has the form:

The left-hand side of a client view mapping is called the depot side, and the right-hand side is the client side.

All client views, regardless of how many mappings they contain, perform the same two functions:

The files that appear in a client workspace are determined by the sum of the depot sides of the mappings within a view. A view might include every file in the depot in a client workspace, only the files within two directories, or even a single file.

Each mapping within a view describes a subset of the complete mapping. Regardless of how many lines there are in a client view, there is always a one-to-one mapping between depot files and client workspace files.

The one-to-one mapping can be straightforward. For instance, the default view in the p4 client form is quite simple:

This mapping maps the entire depot to the entire client workspace; you can edit the default mapping to include only the portion of the depot with which you're working.

More complex mappings are possible. For instance, you can have files in the depot appear in different subdirectories in your client workspace, or even rename files by configuring the mapping. For a complete list of ways to control how and where the depot files appear in your workspace, see "Types of mappings used in views" on page 40.

To determine the exact location of any client file on a workstation, substitute the value of the p4 client form's Root: field for the client name on the client side of the mapping. For example, if the p4 client form's Root: field for the client workspace eds_elm is set to /usr/edk/elm, then the depot file //eds_elm/doc/elmdoc.1 appears in /usr/edk/elm/doc/elmdoc.1 whenever the eds_elm workspace is synced.

Using wildcards in views

Perforce uses three wildcards for pattern matching on the command line and in views. Any combination of these wildcards can be used together.

Wildcard
Meaning

*

Matches anything except slashes; matches files in a single directory.

...

Matches anything including slashes; matches in the current directory all subdirectories.

%%d

Used for parametric substitution in views. See "Changing the order of filename substrings" on page 42 for a full explanation.

Any wildcard used on the depot side of a mapping must be matched with an identical wildcard in the mapping's client side. Any string matched by the wildcard is identical on both sides.

In the client view

the single mapping contains Perforce's "..." wildcard, which matches everything including slashes. The result is that any file in the eds_elm client workspace will be mapped to the same location within the depot's elm_proj file tree. For example, the file //depot/elm_proj/nls/gencat/README is mapped to the client workspace file //eds_elm/nls/gencat/README.

To properly specify file trees, use the "..." wildcard after a trailing slash. (If you specify only //depot/elm_proj..., then the resulting view also includes files and directories such as //depot/elm_project_coredumps, which is probably not what you intended.)

Types of mappings used in views

To control the mapping between depot files and your client workspace, set up your client workspace view by editing the View: field in the p4 client form. You can configure your client workspace to contain only the subset of files you're interested in, map files in one depot subdirectory to different subdirectories in your workspace, name files differently in the depot and your client workspace, and even map in files from other depots.

Direct client-to-depot views

The default view in the p4 client form maps the entire depot into an identical directory tree in the your client workspace. For example, the default view of:

indicates that any file in the directory tree under the client eds_elm will be stored in the identical subdirectory in the depot. For a large site, such a view is inconvenient, as most users only need to see a small subset of the files in the depot.

Including only part of the depot in your client workspace

To have only the portion of the depot in which you're interested appear in your client workspace, change the left-hand side of the View: field to include only the relevant portions of the depot.

Mapping files in the depot to different parts of the client workspace

Views can consist of multiple mappings, which are used to map portions of the depot file tree to different parts of the client file tree. If there is a conflict in the mappings, later mappings have precedence over the earlier ones.

Excluding files and directories from the view

Exclusionary mappings enable you to exclude files and directories from a client workspace by prefacing the mapping with a minus sign ( - ). Whitespace is not permitted between the minus sign and the mapping.

Allowing filenames in the client to differ from depot filenames

Mappings can be used to make the filenames in the client workspace differ from those in the depot.

Each wildcard on the depot side of a mapping must have a corresponding wildcard on the client side of the same mapping. The wildcards are replaced in the copied-to direction by the substring that the wildcard represents in the copied-from direction.

There can be multiple wildcards; the nth wildcard in the depot specification corresponds to the nth wildcard in the client description.

Changing the order of filename substrings

The %%d wildcard matches strings similarly to the * wildcard, but %%d can be used to rearrange the order of the matched substrings.

When two mappings conflict

When you use multiple mappings in a single view, some files can map to two separate places in the depot or on the client. When two mappings conflict in this way, the later mapping overrides the earlier mapping.

Overlaying multiple mappings into one workspace

Overlay mappings enable you to map files from more than one depot directory in the same place in a client workspace. To overlay the contents of a second directory in your client workspace, use a + in front of the mapping.

Overlay mappings are often useful for applying sparse patches within the context of build environments.

Mapping Windows workspaces across multiple drives

To specify a Perforce client workspace that spans multiple Windows drives, use a Root: of null, and specify the drive letters in the client workspace view. Use uppercase drive letters when specifying workspaces across multiple drives. For example:

Client: eds_win
Owner:  edk
Description:
         Ed's Windows Workspace
Root:   null
Options:        nomodtime noclobber
View:
        //depot/main/...     "//eds_win/C:/Current Release/..."
        //depot/rel1.0/...   //eds_win/D:/old/rel1.0/...
        //depot/rel2.0/...   //eds_win/D:/old/rel2.0/...

Mappings that include files from multiple depots

By default, each Perforce server contains a single depot, and the name of the depot is depot. Perforce servers can be configured to use multiple depots. If your administrator has configured more than one depot on your server, the default client workspace form looks like this:

View:
        //depot/...         //eds_elm/depot/...
        //testing/...       //eds_elm/testing/...
        //archive/...       //eds_elm/archive/...

If your system administrator has created multiple depots on your server, you can include files from more than one depot in the same client workspace. The rules for setting up client workspaces that map files from multiple depots are the same as those for client workspace views that map files from a single depot.

See the System Administrator's Guide for information on how to configure multiple depots on a Perforce server.

Client Workspace Specification Options

To change your client workspace specification, use the p4 client command. The Options: field in the p4 client form contains six values, separated by spaces. Each of the six options has two possible settings:

Option
Choice
Default

[no]allwrite

Should unopened files be left writable on the client?

noallwrite

[no]clobber

Should p4 sync overwrite (clobber) writable but unopened files in the client with the same name as the newly synced files?

noclobber

[no]compress

Should the data sent between the client and the server be compressed? Both client and server must be version 99.1 or higher, or this setting will be ignored.

nocompress

[no]crlf

Note: 2000.2 or earlier only!

Should CR/LF translation be performed automatically when copying files between the depot and the client workspace? (On UNIX, this setting is ignored).

crlf

[un]locked

Do other users have permission to edit the client specification? (To make a locked client specification truly effective, be sure to set a password for the client's owner with p4 passwd.)

If locked, only the owner is able to use, edit, or delete the client spec. Note that a Perforce administrator is still able to override the lock with the -f (force) flag.

unlocked

[no]modtime

For files without the +m (modtime) file type modifier:

  • For Perforce clients at the 99.2 level or earlier, if modtime is set, the modification date (on the local filesystem) of a newly synced file is the date and time at the server when the file was submitted to the depot.
  • For Perforce clients at the 2000.1 level or higher, if modtime is set, the modification date (on the local filesystem) of a newly synced file is the datestamp on the file when the file was submitted to the depot.
  • If nomodtime is set, the modification date is the date and time of sync, regardless of Perforce client version.

    For files with the +m (modtime) file type modifier:

  • For Perforce clients at the 99.2 level or earlier, the +m modifier is ignored, and the behavior of modtime and nomodtime is as documented above.
  • For Perforce clients at the 2000.1 level or higher, the modification date (on the local filesystem) of a newly synced file is the datestamp on the file when the file was submitted to the depot, regardless of the setting of modtime or nomodtime on the client.

nomodtime
(i.e. date and time of sync) for most files.

Ignored for files with the +m file type modifier.

[no]rmdir

Should p4 sync delete empty directories in a client if all files in the directory have been removed?

normdir

Changing workspace views or moving your workspace root

You can use p4 client to change your workspace specification at any time, but changes to client workspace specifications do not take effect when you use p4 client. Your changes to a workspace specification take effect only when you use that specification after having updated it.

Because client workspace changes take effect only after you use a changed client specification, changing your workspace view or root can sometimes lead to confusing behavior. To avoid confusion:

Configuring line-ending conventions (CR/LF translation)

Use the LineEnd: field to define what translation (if any) of line-ending character(s) takes place when transferring text files to and from the depot and your client workspace.

Note

The LineEnd: option is new to Perforce 2001.1, and replaces the old convention of specifying crlf or nocrlf in the Options: field.

The LineEnd: field accepts one of five values:

Option
Meaning

local

Use mode native to the client (default)

unix

UNIX-style line endings: LF only

mac

Macintosh-style: CR only

win

Windows-style: CR, LF

share

Shared mode: Line endings are LF with any CR/LF pairs translated to LF-only style before storage or syncing with the depot.

In shared mode, when you sync your client workspace, line endings will be LF. If you edit a text file on a Windows machine, and your editor inserts CRs before each LF, the extra CRs are removed upon file submission and do not appear in the archived file.

The most common use of the share option is for users of Windows workstations who mount their UNIX home directories as network drives; if you sync files onto a UNIX directory mounted as a network drive and edit your files on a Windows workstation, the share option eliminates problems caused by Windows-based editors' insertion of carriage returns in text files.

Multiple workspace roots for cross-platform work

If you are working on more than one operating system, but want to use the same client workspace for each machine, use the AltRoots: field in the p4 client form to specify up to two alternate client workspace root directories.

Note

If you are using a Windows directory in any of your client workspace roots, you must specify the Windows directory as your main workspace Root: and your other workspace root directories in the AltRoots: field.

If you have any AltRoots: configured, your Perforce client program compares the current working directory against the main Root: first, and then against the alternate roots, and uses the first root that matches the current working directory as the workspace root for that command. If no roots match, the main workspace root is used.

For example, if edk's current working directory is under /usr/edk/elm, then Perforce uses the UNIX path as his client workspace root, rather than e:\porting\edk\elm, enabling edk to use the same workspace specification for UNIX and Windows work:

Client: eds_elm
Owner:  edk
Description:
        Created by ed.
Root:   e:\porting\edk\elm
AltRoots:
        /usr/edk/elm
Options:        nomodtime noclobber
View:
        //depot/src/...   //eds_elm/src/...

If you are using multiple workspace roots, you can always find out which workspace root is in effect by examining the Client root: as reported by p4 info.

Deleting a client workspace specification

Use p4 client -d clientname to delete a client workspace specification. Deleting a client specification has no effect on any files in the client workspace or depot; it simply removes the Perforce server's record of the mapping between the depot and the client workspace.

To free up disk space on your local workstation by removing versioned files from an old client workspace, either use p4 sync #none (described in "Specifying File Revisions" on page 53) on the files before deleting the client specification, or delete the files manually using your operating system's file deletion commands after deleting the client specification.

Referring to Files on the Command Line

When you provide file names as arguments to Perforce commands, you can do so either by using the names of the files as they exist in your client workspace (local syntax), or by using Perforce's cross-platform syntax (Perforce syntax).

Local syntax and Perforce syntax

To use local syntax, specify files as you would in your local operating system shell. You can specify file names as absolute paths or relative to your current working directory. If you use relative path components, provide relative paths at the beginning of the file name (that is, ./dir/file.c is allowed, but dir/../dir/file.c is not allowed).

To use Perforce syntax, specify files relative to either a client workspace root ("client syntax"), or the top of the depot tree ("depot syntax"). Unlike local syntax, which uses the conventions of your operating system or command shell, Perforce syntax is identical across different operating systems.

Filenames specified in Perforce syntax always begin with two slashes (//), followed by the client workspace or depot name, followed by the full path of the file relative to the client workspace root or the top of the depot tree. Path components in client and depot syntax are always separated by forward slashes (/), regardless of the component separator used by the local operating system.

The following table shows how to use both forms of Perforce syntax, as well as one form of local syntax, to specify the same file:

Syntax
Example

Depot syntax

//depot/main/src/module/file.c

Client syntax

//myworkspace/module/file.c

Local syntax

C:\Projects\working\module\file.c

Using local syntax and Perforce syntax on the command line

You can use any combination of client syntax, depot syntax, or local syntax to specify files to Perforce commands. Your Perforce client program evaluates any necessary mappings to determine which file is actually used.

For instance, if you supply a filename in client syntax or local syntax, your Perforce client program uses your client workspace view to locate the corresponding file in the depot. If you refer to a filename using depot syntax, your Perforce client program uses your client workspace view to locate the corresponding file in the client workspace.

Client workspace names and depot names on the same Perforce server share the same namespace; it is impossible for a client workspace name to be the same as a depot name.

Using wildcards in Perforce commands and views

Perforce wildcards can be used in both local and Perforce syntax. For example:

Wildcard
Meaning

J*

Files in the current directory starting with J

*/help

All files called help in current subdirectories

...

All files in the current directory and its subdirectories

....c

All files in the current directory and its subdirectories ending in .c

/usr/edk/...

All files in /usr/edk and its subdirectories.

//weasel/...

All files on client (or depot) weasel

//depot/...

All files in the depot named depot

//...

All files in all depots (when used to specify files on the command line)

Perforce wildcards and the command line

The p4 command passes "..." wildcards directly to the Perforce server, where the server expands the wildcard to match against files available on the server. Most command shells ignore the ... and %%d wildcards, but expand the * wildcard, passing the files that match the * as multiple arguments to the p4 command. To have Perforce match the * wildcard against the contents of the depot, escape the * wildcard with quotation marks, backslashes, or whatever convention is used by your shell.

To add multiple files with p4 add, use the * wildcard. You cannot use the "..." wildcard with p4 add to add all files and subdirectories beneath a directory, because the "..." wildcard is expanded by the Perforce server: as files being added do not exist on the server, the server has no means of expanding the "..." wildcard when it is used with the p4 add command. The * wildcard is expanded by the local OS shell, not by the Perforce server, and works with p4 add.

Name and string limitations for filenames and Perforce objects

The pathname component separator (/) and recursive subdirectory wildcards (...) are not permitted in file names, label names, or other identifiers.

Character
Reason

...

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

/

Perforce separator for pathname components.

To refer to files containing the Perforce 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 only to the following four characters:

Character
ASCII expansion

@

%40

#

%23

*

%2a

%

%25

To add a file such as [email protected], force a literal interpretation of special characters by using:

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

After submitting the changelist with the file's addition, you must use the ASCII expansion in order to sync the file to your workspace or edit it within your workspace. For example:

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.

Using spaces in file and path names

Use quotation marks to enclose depot-side or client side mappings of files or directories that contain spaces. For instance, the mapping:

maps all files in //depot/main/release 1.2/doc into the 1.2 documentation subdirectory of client workspace eds_ws.

Other Perforce objects, such as branch names, client names, label names, and so on, can be specified with spaces, but these spaces are automatically converted to underscores by the Perforce server.

Name and description lengths

Descriptions in the forms used by p4 client, p4 branch, and so on, can be of any length. All names given to Perforce objects such as branches, clients, and so on, are limited to 1024 characters.

Internationalization and non-ASCII characters in filenames

In order to support internationalization, Perforce permits the use of "unprintable" (that is, non-ASCII) characters in filenames, label names, client workspace names, and other identifiers. Although non-ASCII characters are permitted in filenames and Perforce identifiers, entering such characters on a command line might require platform-specific solutions. Users of GUI-based file managers can manipulate such files with drag-and-drop operations.

In internationalized environments, there are additional limitations on how Perforce client programs display filenames in non-ASCII character sets. To ensure that all filenames are displayed consistently across all localized machines in an organization using internationalized character sets, all users must use a common code page setting (under Windows, use the Regional Settings applet in the Control Panel; under UNIX, set the LOCALE environment variable).

If you are using Perforce in an internationalized environment, all users must also have P4CHARSET set properly. For details, see the Command Reference.

Specifying File Revisions

Perforce uses the # character to identify file revisions. File revisions in Perforce are denoted by sequentially-increasing integers, beginning from #1 for the first revision, and so on.

The most recent revision of a file is the highest-numbered revision on the server, and is called the head revision. The revision you last synced to your workspace is called the have revision. The zeroth revision of a file is called the null revision, and contains no data.

Specifying file revisions with filenames

All of the commands and examples shown so far have been used against the most recent version of the files to which they apply, but many Perforce commands can act on older file versions.

For instance, if you type p4 sync //workspace/src/lock.c, the latest revision, or head revision, of lock.c is retrieved into your workspace, but you can use revision specifiers against lock.c to obtain the first revision, the revision as of a certain date and time, or the revision of the file as of the submission of a changelist number.

Warning!

Some OS shells treat the revision character # as a comment character if it starts a new word. If your shell is one of these, escape the # before use.

Revision
Specifier

Meaning
Examples

file#n

Revision number

p4 sync lock.c#3

Refers to revision 3 of file lock.c

file@changenum

A change number

p4 sync [email protected]

Refers to the version of lock.c when changelist 126 was submitted, even if no changes to lock.c were submitted in changelist 126.

The file specification used in a command like

p4 sync //depot/[email protected]

refers to the entire depot (//depot/...) as of the changes in changelist 126. (Numbered changelists are explained in Chapter 7, Changelists).

file@labelname

A label name

p4 sync [email protected]

The revision of lock.c in the label called beta (labels are explained in Chapter 8, Labels).

file@clientname

A client name.

The revision of file last taken into client workspace clientname.

p4 sync [email protected]_ws

The revision of lock.c last taken into client workspace lisag_ws

file#none

The nonexistent revision.

p4 sync lock.c#none

Says that there should be no version of lock.c in the client workspace, even if one exists in the depot.

file#head

The head revision, or latest version, of the file.

p4 sync lock.c#head

Except for explicitly noted exceptions, this is identical to referring to the file with no revision specifier.

file#have

The revision on the current client.

This is synonymous to @client where client is the current client name.

p4 sync lock.c#have

The revision of lock.c found in the current client.

file@date

The head revision of the file at 00:00:00 on the morning of that date. Dates are specified as YYYY/MM/DD.

p4 sync [email protected]/05/18

The head revision of lock.c as of 00:00:00, May 18, 1998.

file@"date time"

The head revision of the file in the depot on the given date at the given time. The date is specified as above; the time is specified as HH:MM:SS.

p4 sync [email protected]"1998/05/18 15:21:34"
p4 sync [email protected]/05/18:15:21:34

The head revision of lock.c as of May 18, 1998, at 3:21:34 pm. Both forms shown above are equivalent.

The date and the time must be separated by a single space or a colon, and the entire string should be quoted. The time is specified on the 24-hour clock.

Use four digits when specifying years. If you use dates with two-digit years, the year is assumed to be in the twentieth century.

Date and time specifications are always interpreted in terms of the local time zone of the Perforce server. Because the server represents timestamps in terms of number of seconds since the Epoch (00:00:00 GMT Jan. 1, 1970), if you move your server across time zones, the times recorded on the server will be correct in the new timezone.

You can discover the date, time, offset from GMT, and time zone in effect at your Perforce server by examining the "Server date:" line in the output of p4 info.

Specifying file revisions without filenames

Revision specifications can be provided without file names. If you do not specify a filename with a revision specifier, the command is assumed to apply to the specified revision of all files in the depot or in the client's workspace. For instance, #head refers to the head revisions of every file in the depot, and @labelname refers to the revisions of every file tagged with the label labelname.

Specifying ranges of revisions

Some Perforce commands can be applied to a range of revisions, rather than just a single revision. A revision range is two revision specifications, separated by a comma.

The commands that accept revision range specifications are:

p4 changes

p4 file

p4 integrate

p4 jobs

p4 print

p4 sync

p4 verify

If you provide a revision specifier where a revision range is expected, the specified revision is assumed to be the end of the revision range, and the start of the revision range is assumed to be revision #1. If no revision number or range is given where a revision range is expected, all revisions are assumed (that is, revision #1 through #head).

Perforce File Types

Perforce supports six base file types: text files, binary files, unicode files, native apple files on the Macintosh, Mac resource forks, and UNIX symlinks. File type modifiers can be applied to the base types to enable preservation of timestamps, support for RCS keyword expansion, file compression on the server, and more.

When you add a new file to the depot, Perforce attempts to automatically determine the type of the file. For instance, you use p4 add on a new file, your Perforce client program determines whether or not the file is a regular file or a symbolic link, and then examines the first part of the file to determine whether it's text or binary. If any non-text characters are found, the file is assumed to be binary; otherwise, the file is assumed to be text. (Files of type unicode are detected only when the server is running in unicode mode; for details, see your system administrator.)

After it is set, a file's type is preserved from one revision to the next. You can change or override Perforce's record of a file's type by opening the file with the -t filetype flag:

File types are specified as [basetype]+modifiers, or through the use of file type keywords. File type modifiers can be combined; for instance, to change the file type of your Perl script myscript.pl to executable text with RCS keyword expansion, use p4 edit -t text+kx myscript.pl. You can determine the type of an existing file by using p4 opened or p4 files on the file.

Partial filetypes are also acceptable. For example, to change an existing text file to text+x, use p4 reopen -t +x myscript.pl. Most partial filetype modifiers are added to the filetype, but the storage modifiers (+C, +D, and +F) replace the file's storage method. To remove a modifier, you must specify the full filetype.

A file's type determines whether full file or delta storage is used on the Perforce server. By default, binary files are stored in full on the server. For text files, only the changes (the "deltas') associated with each revision are stored: this is called delta storage. Perforce uses RCS format to store deltas. When delta storage is used, you can perform merges and line-by-line file comparisons between file revisions. Files that are stored in their full form cannot be merged or compared.

Some file types are automatically compressed to gzip format when stored in the depot. The compression occurs when you submit the file, and decompression happens when you sync (copy the file from the server to the workspace). The client workspace always contains the file as it was submitted to the depot.

Warning!

Do not try to use delta storage against binary files by manually changing the file type to text. Unpredictable results may occur if you attempt to submit a binary file with its filetype manually set to text.

Base file types

The base Perforce file types are:

Keyword
Description
Comments
Server Storage Type

text

Text file

Treated as text on the client. Line-ending translations are performed automatically on Windows and Macintosh clients.

delta

binary

Non-text file

Accessed as binary files on the client. Stored compressed within the depot.

full file,
compressed

symlink

Symbolic link

UNIX clients (and the BeOS client) access these as symbolic links. Non-UNIX clients treat them as (small) text files.

delta

apple

Multi-forked Macintosh file

AppleSingle storage of Mac data fork, resource fork, file type and file creator. New to Perforce 99.2.

For full details, please see the Mac platform notes at http://www.perforce.com/perforce/technical.html

full file,
compressed, AppleSingle format.

resource

Macintosh resource fork

The only file type for Mac resource forks in Perforce 99.1 and before. This is still supported, but we recommend using the new apple file type instead.

For full details, please see the Mac platform notes at http://www.perforce.com/perforce/technical.html

full file,
compressed

unicode

Unicode file

Perforce servers operating in internationalized mode support a Unicode file type. These files are translated into the local character set.

For details, see the System Administrator's Guide.

Stored as UTF-8

File type modifiers

The file type modifiers are:

Modifier
Description
Comments

+x

Execute bit set on client

Used for executable files.

+w

File is always writable on client

+ko

Old-style keyword expansion

Expands only the $Id$ and $Header$ keywords:

This pair of modifiers exists primarily for backwards compatibility with versions of Perforce prior to 2000.1, and corresponds to the +k (ktext) modifier in earlier versions of Perforce.

+k

RCS keyword expansion

Expands RCS (Revision Control System) keywords. RCS keywords are case-sensitive.

When using keywords in files, a colon after the keyword (e.g., $Id:$) is optional.

Supported keywords are:

  • $Id$
  • $Header$
  • $Date$
  • $DateTime$
  • $Change$
  • $File$
  • $Revision$
  • $Author$

+l

Exclusive open (locking)

If set, only one user at a time will be able to open a file for editing.

Useful for binary file types (e.g., graphics) where merging of changes from multiple authors is meaningless.

+C

Server stores the full compressed version of each file revision

Default server storage mechanism for binary files.

+D

Server stores deltas in RCS format

Default server storage mechanism for text files.

+F

Server stores full file per revision

Useful for long ASCII files that aren't read by users as text, such as PostScript files.

+S

Only the head revision is stored on the server

Older revisions are purged from the depot upon submission of new revisions. Useful for executable or .obj files.

+m

Preserve original modtime

The file's timestamp on the local filesystem is preserved upon submission and restored upon sync. Useful for third-party DLLs in Windows environments.

File type keywords

The following table lists the Perforce file type keywords and their equivalent base file types and modifiers:

Old Keyword
Description
Base Filetype
Modifiers

text

Text file

text

none

xtext

Executable text file

text

+x

ktext

Text file with RCS keyword expansion

text

+k

kxtext

Executable text file with RCS keyword expansion

text

+kx

binary

Non-text file

binary

none

xbinary

Executable binary file

binary

+x

ctext

Compressed text file

text

+C

cxtext

Compressed executable text file

text

+Cx

symlink

Symbolic link

symlink

none

resource

Macintosh resource fork

resource

none

uresource

Uncompressed Macintosh resource fork

resource

+F

ltext

Long text file

text

+F

xltext

Executable long text file

text

+Fx

ubinary

Uncompressed binary file

binary

+F

uxbinary

Uncompressed executable binary file

binary

+Fx

tempobj

Temporary object

ubinary

+FSw

ctempobj

Temporary object (compressed)

cbinary

+Sw

xtempobj

Temporary executable object

ubinary

+FSwx

xunicode

Executable unicode

unicode

+x

Overriding file types with the typemap table

Some file formats (for example, Adobe PDF files and Rich Text Format files) are actually binary files, but can sometimes be erroneously detected by Perforce as being of type text. Your system administrator can use the p4 typemap command to set up a table that matches file names to specific Perforce file types.

Whenever you open a new file for add, Perforce checks the typemap table. If the file matches an entry in the table, Perforce uses the file type specified in the table rather than attempting to guess the file's type by examining its contents. To override file types in the typemap table, specify the file type on the command line with the -t filetype flag.

Preserving timestamps with the +m modifier

The default behavior of Perforce is to update the timestamp on files in your client workspace when you sync the files. If you need to preserve a file's original timestamp, use the modtime (+m) file type modifier. Doing so enables you to ensure that the timestamp of a file in a client workspace after a p4 sync is the original timestamp existing on the file at the time of changelist submission (that is, not the time at the Perforce server at time of submission, and not the time on the client workstation at the time of sync).

The +m modifier is useful when developing using the third-party DLLs often encountered in Windows environments. Because the timestamps on such files are often used as proxies for versioning information (both within the development environment and also by the operating system), it is sometimes necessary to preserve the files' original timestamps regardless of a Perforce user's client settings. If you use the +m modifier on a file, Perforce ignores the modtime ("file's timestamp at time of submission") or nomodtime ("date and time on the client at time of sync") options in the p4 client form when syncing the file, and always restores the file's original timestamp at the time of changelist submission.

Expanding RCS keywords with the +k modifier

If you use the +k modifier to activate RCS keyword expansion for a file, RCS keywords are expanded as follows:

Keyword
Expands To
Example

$Id$

File name and revision number in depot syntax

$Id: //depot/path/file.txt#3 $

$Header$

Synonymous with $Id$

$Header: //depot/path/file.txt#3 $

$Date$

Date of last submission in format YYYY/MM/DD

$Date: 2000/08/18 $

$DateTime$

Date and time of last submission in format YYYY/MM/DD hh:mm:ss

Date and time are as of the local time on the Perforce server at time of submission.

$DateTime: 2000/08/18 23:17:02 $

$Change$

Perforce changelist number under which file was submitted

$Change: 439 $

$File$

File name only, in depot syntax (without revision number)

$File: //depot/path/file.txt $

$Revision$

Perforce revision number

$Revision: #3 $

$Author$

Perforce user submitting the file

$Author: edk $

Forms and Perforce Commands

Certain Perforce commands, such as p4 client and p4 submit, display a form that you must fill in while using a text editor. When you change the form and exit the editor, the form is parsed by Perforce, checked for errors, and used to complete the command. If there are errors in the form, Perforce displays an error message and you must edit the form again.

The rules of form syntax are as follows: field names must be against the left margin and end with a colon, and field values must either be on the same line as the field name, or indented on the lines beneath the field name. Some keywords, such as the Client: field in the p4 client form, take a single value; other fields, such as Description:, take a block of text; and others, like View:, take multiple values, one per line.

Certain fields, like Client: in p4 client, are read-only and cannot have their values changed; other fields, like Description: in p4 submit, must have their values changed. When in doubt about which fields can (or must) be modified, see the Command Reference or use p4 help command.

Changing the default forms editor

To override the default editor on either Windows or UNIX, set the Perforce environment variable P4EDITOR to the full path of your editor of choice.

On Windows, the default text editor for Perforce forms is Notepad. On UNIX, the default text editor for Perforce forms is whatever editor is specified by the EDITOR environment variable, or vi if no EDITOR is specified.

Scripting with Perforce forms

Any commands that require you to fill in a form, such as p4 client and p4 submit, can read a from standard input with the -i flag. Similarly, you can use the -o flag to direct a form to standard output.

These two flags are primarily used in scripts that access Perforce: use the -o flag to read a form, process the strings representing the form's fields within your script, and then use the -i flag to send the processed form back to the Perforce client program.

For instance, to create a new job by means of a script, use p4 job -o > tempfile to write a blank job specification to a temporary file, then add information to the proper lines in tempfile, and then use a command such as p4 job -i < tempfile to read the edited form and store the job data in Perforce, just as if a user had entered the job data from within an editor.

The commands that display forms and support the -i and -o flags are:

p4 branch

p4 change

p4 client

p4 job

p4 label

p4 protect

p4 submit

p4 typemap

p4 user

Note

p4 submit can take the -i flag, but not the -o flag.

General Reporting Commands

Many reporting commands have specialized functions, and these are discussed in later chapters. The following reporting commands give the most generally useful information; all of these commands can take file name arguments, with or without wildcards, to limit reporting to specific files. Without the file arguments, the reports are generated for all files.

The following Perforce reporting commands generate information on depot files, not files within the client workspace. When files are specified in local or client syntax on the command line, Perforce uses the client workspace view to map the specified files to their locations in the depot.

Command
Meaning

p4 filelog

Generates a report on each revision of the file(s), in reverse chronological order.

p4 files

Lists file name, latest revision number, file type, and other information about the named file(s).

p4 sync -n

Tells you what p4 sync would do, without doing it.

p4 have

Lists all the revisions of the named files within the client that were last gotten from the depot. Without any files specifier, it lists all the files in the depot that the client has.

p4 opened

Reports on all files in the depot that are currently open for edit, add, delete, branch, or integrate within the client workspace.

p4 print

Lists the contents of the named file(s) to standard output.

p4 where

Given a file argument, displays the mapping of that file within the depot, the client workspace, and the local OS.

Revision specifiers can be used with all of these reporting commands, for example p4 files @clientname can be used to report on all the files in the depot that are currently found in client workspace clientname. See Chapter 11, Reporting and Data Mining, for a more detailed discussion of each of these commands.


Perforce 2005.1 User's Guide
<< Previous Chapter
Perforce Basics:
Quick Start

Table of Contents
Index
Perforce on the Web
Next Chapter >>
Perforce Basics:
Resolving File Conflicts

Please send comments and questions about this manual to [email protected].
Copyright 1997-2005 Perforce Software. All rights reserved.
Last updated: 05/12/05