Perforce 2002.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, refer to Chapter 3, Perforce Basics: Quick Start.

Description of the Client Workspace


A Perforce client workspace is a collection of source files managed by Perforce on a host. Each collection is given a name which identifies the client workspace to the Perforce server. By default, the name is simply the host's name, but this can be overridden by the environment variable P4CLIENT. There can be more than one Perforce client workspace on a client host.

All files within a Perforce client workspace share a common root directory, called the client root. In the degenerate case, the client root can be the host's root, but in practice the client root is the lowest level directory under which the managed source files sit.

Perforce manages the files in a client workspace in three direct ways:

The entire Perforce client workspace state is tracked by the Perforce server. The server knows what files a client workspace has, where they are, and which files have write permission turned on.

Perforce's management of a client workspace requires a certain amount of cooperation from the user. Because client files are ordinary files with write permission turned off, willful users can circumvent the system by turning on write permission, directly deleting or renaming files, or otherwise modifying the file tree supposedly under Perforce's control.

Perforce counters this with two measures: first, Perforce has explicit commands to verify that the client workspace state is in accord with the server's recording of that state; second, Perforce tries to make using Perforce at least as easy as circumventing it. For example: to make a temporary modification to a file, it is easier to use Perforce than it is to copy and restore the file manually.

Files not managed by Perforce may also be under a client's root, but are ignored by Perforce. For example, Perforce may manage the source files in a client workspace, while the workspace also holds compiled objects, libraries, and executables, as well as a developer's temporary files.

In addition to accessing the client files, the p4 client program sometimes creates temporary files on the client host. Otherwise, Perforce neither creates nor uses any files on the client host.

Wildcards


Perforce uses three wildcards for pattern matching. Any number and combination of these can be used in a single string:

Wildcard
Meaning

*

Matches anything except slashes; matches only within a single directory.

...

Matches anything including slashes; matches across multiple directories.

%d

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

The "..." wildcard is passed by the p4 client program to the Perforce server, where it is expanded to match the corresponding files known to p4d. The * wildcard is expanded locally by the OS shell before the p4 command is sent to the server, and the files that match the wildcard are passed as multiple arguments to the p4 command. To have Perforce match the * wildcard against the contents of the depot, it must be escaped, usually with quotes or a backslash. Most command shells don't interfere with the other two wildcards.

Wildcards and "p4 add"

The "..." wildcard can't be used with the p4 add command. The "..." wildcard is expanded by the Perforce server, and since the server doesn't know what files are being added (after all, they're not in the depot yet), it can't expand that wildcard. The * wildcard may be used with p4 add, as it is expanded by the local OS shell, not by the p4d server.

Mapping the Depot to the Client Workspace


Just as a client name is simply an alias for a particular directory on the client machine, a depot name is an alias for a directory on the Perforce server. The relationship between files in the depot and files in the client workspace is described in the client view, and it is set with the p4 client command.

When you type p4 client, Perforce displays a variation of the following form:

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 client files get stored in the depot, and where depot files are copied to in the client.

Note

The p4 client form has more fields than are described here. For a full discussion, please see the Perforce Command Reference.

Multiple depots

By default, there is a single depot in each Perforce server, and the name of the depot is depot. The Perforce system administrator can create multiple depots on the same Perforce server.

If your system administrator has created multiple depots on your server, the default client view will look something like this:

View:
        //depot/...      //eds_elm/depot/...
        //user_depot/... //eds_elm/user_depot/...
        //projects/...   //eds_elm/projects/...

The Perforce System Administrator's Guide explains how to create multiple depots.

Using views

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

The right-hand side of each mapping describes one or more files within the 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.

The default view in the example above is quite simple: it maps the entire depot to the entire client workspace. Views can contain multiple mappings, and can be much more complex, but all client views, no matter how elaborate, perform the same two functions:

This is determined by the sum of the depot sides of the mappings within a view. A view might allow the client workspace to retrieve every file in the depot, or only those files within two directories, or only a single file.

Each mapping within a view describes a subset of the complete mapping. The one-to-one mapping might be straightforward; for example, the client workspace file tree might be identical to a portion of the depot's file tree. Or it can be oblique; for example, a file might have one name in the depot and another in the client workspace, or be moved to an entirely different directory in the client workspace. No matter how the files are named, there is always a one-to-one mapping.

To determine the exact location of any client file on the host machine, 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 eds_elm is set to /usr/edk/elm, then the file //eds_elm/doc/elmdoc.1 will be found on the client host in /usr/edk/elm/doc/elmdoc.1.

Windows

On Windows machines, the Perforce client must be specified in a slightly different way if it is to span multiple drives. For details, please see the platform notes at http://www.perforce.com/perforce/technical.html

Wildcards in views

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

By changing the View: field, it is possible to map only part of a depot to a client workspace. It is even possible to map files within the same depot directory to different client workspace directories, or to have files named differently in the depot and the client workspace. This section discusses Perforce's mapping methods.

Direct client-to-depot views

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

indicates that any file in the directory tree under the client eds_elm will be stored in the identical subdirectory in the depot. This view is usually considered to be overkill, as most users only need to see a subset of the files in the depot.

Mapping the full client to only part of the depot

Usually, you'll only want to see part of the depot. Change the left-hand side of the View: field to point to only the relevant portion of the depot.

Mapping files in the depot to different parts of the client

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 allow files and directories to be excluded from a client workspace. This is accomplished by prefacing the mapping with a minus sign ( - ). Whitespace is not allowed 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.

Two mappings can conflict and fail

When you use multiple mappings in a single view, some files may map to two separate places in the depot or on the client. When a file doesn't map to the same place in both directions, Perforce ignores that file.

In older versions of Perforce, this was often used as a trick to exclude particular files from the client workspace. Because Perforce now has exclusionary mappings, this type of mapping is no longer useful, and should be avoided.

Editing Existing Client Specifications


You can use p4 client at any time to change the client workspace specification.

Note that changing a client specification has no immediate effect on the locations of any files; the locations of files in your workspace are affected only when the client specification is used in subsequent commands.

This is particularly important for two types of client spec changes, specifically changes to the client view and changes to the client root:

Deleting an existing client specification

An existing client workspace specification can be deleted with p4 client -d clientname. 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 delete existing files from a client workspace, use p4 sync #none (described in "Specifying Older File Revisions" on page 46) on the files before deleting the client specification, or use the standard local OS deletion commands after deleting the client specification.

Client specification options

The Options: field contains six values, separated by spaces. Each of the six options have two possible settings.

The following table provides the option values and their meanings:

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 superuser 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

Line-ending conventions (CR/LF translation)

The LineEnd: field controls the line-ending character(s) used for text files in the 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.

When you sync your client workspace, line endings will be LF. If you edit the file on a Windows machine, and your editor inserts CRs before each LF, the extra CRs will not appear in the archive file.

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

Referring to Files on the Command Line


File names provided as arguments to Perforce commands can be referred to in one of two ways: by using the names of the files in the client workspace, or by providing the names of the files in the depot. When providing client workspace file names, you may give the name in either local syntax or Perforce syntax.

Local syntax

Local syntax is simply a file's name as specified by the local shell or OS. This name may be an absolute path, or may be specified relative to the current directory, although it can only contain relative components at the beginning of the file name (that is, it doesn't allow sub/dir/./here/foo.c). On UNIX, Ed could refer to the README file at Elm's top level as /usr/edk/elm/README, or in a number of other ways.

Perforce syntax

Perforce provides its own filename syntax which remains the same across operating systems. Filenames specified in this way begin with two slashes and the client or depot name, followed by the path name of the file relative to the client or depot root directory.

The components of the path are separated by slashes.

Examples of Perforce syntax

//depot/...

//elm_client/docs/help.1

Perforce syntax is sometimes called depot syntax or client syntax, depending on whether the file specifier refers to a file in the depot or on the client, but both forms of file specification work the same way.

Providing files as arguments to commands

Because the client view provides a one-to-one mapping between any file in the client workspace and any file in the depot, any file can be specified within any Perforce command in client syntax, depot syntax, or local syntax. A depot's file specifier can be used to refer to a file in the client, and vice versa. Perforce will do the necessary mapping to determine which file is actually used.

Any filenames provided to Perforce commands can be specified in any valid local syntax, or in Perforce syntax by depot or client. If a client filename is provided, Perforce uses the client view to locate the corresponding file in the depot. If a depot filename is given, the client view is used to locate the corresponding file in the client workspace.

Client names and depot names in a single Perforce server share the same namespace, so Perforce will never confuse a client name with a depot name. Client workspace names and depot names can never be the same.

Note

The point of this section is worth repeating: any file can be specified within any Perforce command in client syntax, depot syntax, or local syntax. The examples in this manual will use these syntaxes interchangeably.

Wildcards and Perforce syntax

Perforce wildcards may be mixed with both local or 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 under the current directory and its subdirectories

.../*.c

All such files ending in .c

/usr/edk/...

All files under /usr/edk

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

Name and String Limitations


Illegal characters in filenames and Perforce objects

In order to support internationalization, Perforce allows the use of "unprintable" (i.e. non-ASCII) characters in filenames, label names, client workspace names, and other identifiers.

Perforce's wildcards and the revision-specifying characters @ and #, are not allowed in file names, label names, or other identifiers:

Character
Reason

@

Perforce revision specifier for date, label name, or changelist number.

#

Perforce revision specifier for revision numbers.

*

Perforce wildcard: matches anything, works within a single directory

...

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

%

Perforce wildcard: %0 through %9 are used for positional substitutions.

/

Perforce separator for pathname components.

Observe that most of these 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.

Caveats on non-ASCII filenames

Although non-ASCII characters are allowed in filenames and Perforce identifiers, entering them from the command line may require platform-specific solutions. Users of GUI-based file managers can manipulate such files with drag-and-drop operations.

For internationalization purposes, there are some limitations on how filenames with non-ASCII character sets are displayed. For Release 2001.1, all users should use a common code page setting (under Windows, use the Regional Settings applet in the Control Panel; under UNIX, set the LOCALE environment variable) in order to ensure that all filenames are displayed consistently across all machines in your organization.

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

Caveats on using spaces in filenames

Filenames can include spaces, but require some care as to their specification in client views and root mappings. If you use spaces in a client view or client root, quote the string in which the space appears.

Make sure not to quote spaces that divide two separate strings; for example, a client mapping containing a directory named "my projects" would be quoted like this:

Other Perforce objects, such as branch names, client names, label names, and so on, may be specified with spaces, but these spaces will be 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, may be of any length. Similarly, all names given to Perforce objects such as branches, clients, and so on, are also limited to 1024 characters.

Specifying Older File Revisions


All of the commands and examples we've seen thus far have been used to operate only on the most recent revisions of particular files, but many Perforce commands can act on older file versions. For example, if Ed types p4 sync //eds_elm/src/lock.c, the latest revision, or head revision, of lock.c is retrieved, but older revisions can be retrieved by tacking a revision specification onto the end of the file name.

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@n

A change number

p4 sync lock.c@126

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

p4 sync //depot/...@126

Refers to the state of the entire depot at changelist 126 (numbered changelists are explained in Chapter 7, Changelists).

file@labelname

A label name

p4 sync lock.c@beta

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 lock.c@lisag_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 lock.c@1998/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 lock.c@"1998/05/18 15:21:34"
p4 sync lock.c@1998/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.

Warning! Perforce allows you to search on dates with two-digit years, but these years are assumed to fall in the twentieth century. For safety's sake, use four-digit years.

In all cases, if a file doesn't exist at the given revision number, it appears as if the file doesn't exist at all. Thus, using a label to refer to a file that isn't in the label is indistinguishable from referring to a file that doesn't exist at all.

Date and time specifications are always interpreted with respect to the local time zone of the Perforce server. Note that because the server stores times internally 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 automatically be reported in the new timezone.

The date, time, and time zone in effect at your Perforce server are displayed in the "Server date:" line in the output of p4 info.

Using revision specifications without filenames

Revision specifications can be provided without file names. This limits the command's action to the specified revision of all files in the depot or in the client's workspace. Thus, #head refers to the head revisions of all files in the depot, and @labelname refers to the revisions of all files in the named label.

Revision Ranges


A few Perforce client commands can limit their actions to a range of revision numbers, rather than just a single revision. A revision range is two revision specifications, separated by a comma.

If only a single revision is given where a revision range is expected, the named revision specifies the end of the range, and the start of the range is assumed to be 1. If no revision number or range is given where a revision range is expected, the default is all revisions.

The commands that accept revision range specifications are:

p4 changes

p4 file

p4 integrate

p4 jobs

p4 print

p4 sync

p4 verify

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 are then applied to the base types allowing for support of RCS keyword expansion, file compression on the server, and more.

Perforce attempts to determine the type of the file automatically: when a file is opened with p4 add, Perforce first decides if 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 internationalized mode; for details, see your system administrator.)

Some file formats (for example, Adobe PDF files, and Rich Text Format files) are actually binary files, but can sometimes be mistakenly detected by Perforce as being of type text. For these files, your system administrator can use the p4 typemap command to set up a table matching Perforce file types to file name specifications.

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 the file type it would have otherwise used. You can override the file type specified in the typemap table by specifying it on the command line with the -t filetype modifier.

Once set, a file's type is normally inherited from one revision to the next, but can be overridden or changed with the -t flag:

The filetype argument is specified as basetype+modifiers. File type modifiers may 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. Full listings of the base file types and their modifiers are provided below.

The type of an existing file can be determined with p4 opened or p4 files.

File revisions of binary files are normally stored in full within the depot, but only changes made to text files since the previous revision are normally stored. This is called delta storage, and Perforce uses RCS format to store its deltas. The file's type determines whether full file or delta storage is used. When delta storage is used, file merges and file compares can be performed. Files that are stored in their full form can't be merged or compared. (RCS format and delta storage are described in more detail at the start of the next chapter).

Some of the file types are compressed to gzip format for storage in the depot. The compression occurs during the submission process, and decompression happens while syncing. The client workspace always contains the file as it was submitted.

Warning!

Do not try to fool Perforce into storing binary files in delta storage by changing the file type to text! If you add a file that contains a ^Z as text from a Windows client, only the part of the file up to the ^Z will be stored in the depot.

Note

Versions of Perforce prior to 99.1 used a very different, somewhat limited, set of file types. These types have been maintained for backwards compatibility.

Mappings between the old and new file types are described in the Perforce Command Reference.

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

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 overwritten within the depot. 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.

The modtime (+m) modifier is a special case: It is intended for use by developers who need to preserve a file's original timestamp. (Normally, Perforce updates the timestamp when a file is synced.) It allows a user to ensure that the timestamp of a file in a client workspace after a p4 sync will be the original timestamp existing on the file at the time of submission (that is, not the time at the Perforce server at time of submission, and not the time on the client at the time of sync).

The most common case where this is useful is development involving 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.

The +m modifier on a file allows this to happen; if set, Perforce ignores the modtime ("file's timestamp at time of submission") or nomodtime ("date and time on the client at time of sync") setting at the p4 client level when syncing the file, and always restore the file's original timestamp at the time of submit.

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, present a form to the user to be filled in with values. This form is displayed in the editor defined in the environment variable P4EDITOR. When the user changes the form and exits the editor, the form is parsed by Perforce, checked for errors, and used to complete the command operation. If there are errors, Perforce gives an error message and you must try again.

The rules of form syntax are simple: keywords must be against the left margin and end with a colon, and values must either be on the same line as the keyword or indented on the lines beneath the keyword. Only the keywords already present on the form are recognized. 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 a list of lines.

Certain fields, like Client: in p4 client, can't have their values changed; others, like Description: in p4 submit, must have their values changed. If you don't change a field that needs to be changed, or vice versa, the worst that will happen is that you'll get an error. We've done our best to make these cases as self-evident as possible. When in doubt, consult the Perforce Command Reference or use p4 help command.

Reading forms from standard input;
Writing forms to standard output

Any commands that require the user to fill in a form, such as p4 client and p4 submit, can read the form from standard input with the -i flag. Similarly, the -o flag can be used to write a form specification 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 within your script, and finally, use the -i flag to send the processed form back to Perforce.

For example, to create a new job within a script you could first use p4 job -o > tempfile to read a blank job specification, then add information to the proper lines in tempfile, and finally use a command like p4 job -i < tempfile to store the new job in Perforce.

The commands that display forms and can therefore use these flags are:

p4 branch

p4 change

p4 client

p4 job

p4 label

p4 protect

p4 submit*

p4 typemap

p4 user

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

These reports always generate information on depot files, not files within the client workspace. As with any other Perforce command, when a client file is provided on the command line, Perforce maps it to the proper depot file.

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 clientname. See Chapter 11, Reporting and Data Mining, for a more detailed discussion of each of these commands.


Perforce 2002.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-2002 Perforce Software. All rights reserved.
Last updated: 04/03/02