It is assumed that the material in the Quick Start chapter has been read and properly digested.

Description of the Client Workspace

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 will sit.

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

• it creates, updates, or deletes files as required in the workspace when the user requests Perforce to synchronize the client workspace with the depot;

• it turns on write permission when the user requests to edit a file;

• it turns off write permission and submits updated versions back to the depot when the user has finished editing the file and wishes to submit his or her changes.

Perforce's management of a client workspace requires a certain amount of cooperation from the user. Since client files are just plain 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, 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

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"

Mapping the Depot to the Client Workspace

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

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.

Multiple Depots

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

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

Using Views

//depotname/file_specification

//clientname/file_specification

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

• The client view determines which files in the depot can be seen by a client workspace. 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.

• It constructs a one-to-one mapping between files in the depot and files in the client workspace. 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.

Wildcards in Views

In the client view

//depot/elm_proj/...    //eds_elm/...

Types of Mappings

Direct Client-to-Depot Views

//depot/... //eds_elm/...

Mapping the Full Client to only Part of the Depot

Example:  Mapping part of the depot to the client workspace.

Bettie is rewriting the documentation for Elm, which is found in the depot within its doc subdirectory. Her client is named elm_docs, and her client root is /usr/bes/docs; she types p4 client and sets the View: field as follows:

//depot/elm_proj/doc/... //elm_docs/...

The files in //depot/elm_proj/doc will be mapped to /usr/bes/elm_docs.

Mapping Files in the Depot to a Different Part of the Client

Example:  Multiple mappings in a single client view.

The elm_proj subdirectory of the depot contains a directory called doc, which has all the Elm documents. Included in this directory are four files named elm-help.0 through elm-help.3. Mike wants to separate these four files from the other documentation files in his client workspace, which is called mike_elm.

To do this, he creates a new directory in his client workspace called help; it's located at the same level as his doc directory. The four elm-help files will go here; he fills in the View: field of the p4 client form as follows:

View:         //depot/...                        //mike_elm/...         //depot/elm_proj/doc/elm-help.*    //mike_elm/help/elm-help.*

Any file whose name starts with elm-help within the depot's doc subdirectory will be caught by the later mapping and appear in Mike's workspace's help directory; all other files are caught by the first mapping and will appear in their normal location. Conversely, any files beginning with elm-help within Mike's client workspace help subdirectory will be mapped to the doc subdirectory of the depot.

Excluding Files and Directories from the View

Example:  Using views to exclude files from a client workspace.

Bill, whose client is named billm, wants to view only source code; he's not interested in the documentation files. His client view would look like this:

View:         //depot/elm_proj/...         //billm/...         -//depot/elm_proj/doc/...    //billm/doc/...

Since later mappings have precedence over earlier ones, no files from the depot's doc subdirectory will ever be copied to Bill's client. Conversely, if Bill does have a doc subdirectory in his client, no files from that subdirectory will ever be copied to the depot.

Allowing Filenames in the Client to differ from Depot Filenames

Example:  Files with different names in the depot and client workspace.

Mike wants to store the files as above, but he wants to take the elm-help.X files in the depot and call them helpfile.X in his client workspace. He uses the following mappings:

View:         //depot/elm_proj...                //mike_elm/...         //depot/elm_proj/doc/elm-help.*    //mike_elm/help/helpfile.*

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

Example:  Changing string order in client workspace names.

Mike wants to change the names of any files with a dot in them within his doc subdirectory in such a way that the file's suffixes and prefixes are reversed in his client workspace. For example, he'd like to rename the Elm.cover file in the depot cover.Elm in his client workspace. (Mike can be a bit difficult to work with). He uses the following mappings:

View:         //depot/elm_proj/...          //mike_elm/...         //depot/elm_proj/doc/%1.%2    //mike_elm/doc/%2.%1

Two Mappings Can Conflict and Fail

Example:  Mappings that conflict and fail.

Joe has constructed a view as follows:

View:         //depot/elm_proj/...      //joe/elm/...         //depot/nowhere/*         //joe/elm/doc/*

The depot file //depot/elm_proj/doc/help would map to //joe/elm/doc/help, but the same file in the client workspace would map back to the depot via the higher-precedence second line to //depot/nowhere/help. Because the file would be written back to a different location in the depot than where it was read from, Perforce doesn't map this name at all.

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

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:

• If you change only the value of the client workspace View: field with p4 client, perform a p4 sync immediately afterward. The files in the client workspace will be deleted from their old locations and written to their new locations.

• If you use p4 client to change the client workspace Root:, use p4 sync #none to remove the files from their old location in the workspace before using p4 client to change the client root. After using p4 client to change the root directory, perform a p4 sync to copy the files to their new locations within the client view. (If you forget to perform the p4 sync #none before changing the client view, you can always remove the files from their client workspace locations manually).

  !Warning!

  It's not a good idea to change both the client Root: and the client View: at the same time. Change either the Root: or the View: according to the instructions above, make sure that the files are in place in the client workspace, and then change the other.

Deleting an Existing Client Specification

To delete existing files from a client workspace, use p4 sync #none (described in "How to Specify Older File Revisions" on page 35) on the files before deleting the client specification, or use the standard local OS deletion commands after deleting the client specification.

Client Specification Options

Referring to Files on Command Lines

Local Syntax

Perforce Syntax

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 the syntax is the same in either case.

Providing Files as Arguments to Commands

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.

Example:  Uses of different syntaxes to refer to a file.

Ed wants to delete the src/lock.c file. He can give the p4 delete command in a number of ways:

While in his client root directory, he could type

p4 delete src/lock.c

or, while in the src subdirectory, he could type

p4 delete lock.c

or, while in any directory on the client host, he can type

p4 delete //eds_elm/src/lock.c

or

p4 delete //depot/elm_proj/src/lock.c

or

p4 delete /usr/edk/elm/src/lock.c

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.

Wildcards and Perforce Syntax

Name and String Limitations

Illegal characters in filenames and Perforce objects

The following characters cannot be used in file names:

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.

Special notes on using spaces

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:

//depot/projects/foo/... "//aclient/my projects/foo/..."

Name and description lengths

How to Specify Older File Revisions

In all cases, if a file doesn't exist at the given revision number, it will appear 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

Example:  Retrieving files using revision specifiers.

Ed wants to retrieve all the doc files into his Elm doc subdirectory, but he wants to see only those revisions that existed at change number 30. He types

p4 sync //eds_elm/doc/*@30

Later, he creates another client for a different user. The new client should have all of the file revisions that Ed last synced. Ed sets up the new client specification and types

p4 sync //depot/elm_proj/...@eds_elm

He could have typed

p4 sync @eds_elm

and the effect would have been the same.

Example:  Removing files from the client workspace.

Another client needs all its files removed, but these files shouldn't be deleted from the depot. Ed sets P4CLIENT to the correct clientname, and types

p4 sync #none

The files are removed from his workspace ("synced to the nonexistent revision") , but not from the depot.

Revision Ranges

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:

Example:  Listing changes with revision ranges.

A release manager needs to see a list of all changes to the Elm project in July. He types:

p4 changes //depot/elm_proj/...@2000/7/1,2000/7/31

The resulting list of changes looks like this:

Change 632 on 2000/07/1 by edk@eds_elm 'Started work'
Change 633 on 2000/07/1 by edk@eds_elm 'First test build with bug fix'
...
Change 673 on 2000/07/31 by edk@eds_elm `Final build for QA'

He can then use p4 describe change# against any desired change for a full description.

File Types

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.

Some file formats (e.g., Adobe PDF, Rich Text Format) 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 will use 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:

• p4 add -t filetype filespec will add the files as the type you've specified.

• p4 edit -t filetype filespec will open the file for edit; when the files are submitted, their type will be changed.

• p4 reopen -t filetype filespec will change the type of a file that's already open for add or edit.

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 will always contain the file as it was submitted.

The base Perforce file types are:

The file type modifiers are:

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 (i.e., 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 will ignore 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:

Forms and Perforce Commands

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 User Guide or use p4 help command.

Reading Forms from Standard Input;
Writing Forms to Standard Output

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 submit can take the -i flag, but not the -o flag.

General Reporting Commands

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.

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. The reporting chapter, chapter 11, contains a more detailed discussion of each of these commands.