[Top] [Prev] [Next]

Perforce Basics:
The Details

The Quick Start chapter explained the basics of using perforce, but discussion of the practical details were deferred. This chapter, which supplements the Quick Start, covers the dry perforce rules. The topics discussed include views, mapping depots to client workspaces, perforce wildcards, rules for referring to older file revisions, file types, form syntax, and mapping depots to client workspaces.

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

Description of the Client Workspace

A perforce client workspace is a collection of source files managed by perforce on a host. Each such collection is given a name which identifies the client workspace to the perforce server. The name is by default simply the host's name but that 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 will sit. (On NT, the perforce client workspace must reside entirely on a single logical drive, as there is no universal root directory.)

perforce manages the files in a client workspace in a few direct ways. It creates, updates, or deletes files 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; and turns off write permission and submits updated versions back to the depot when the user is finished editing the file.

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. 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, and they are largely 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

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.

Mapping the Depot to the Client Workspace

Just as a client name is nothing more than 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 set in the client view, and it is set with the p4 client command. When p4 client is typed, a variation of the following form is displayed: 
Client: eds_elm
Owner: ed
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.

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

	//depotname/file_specification
The right-hand side of each mapping describes one or more files within the client workspace, and has the form

	//clientname/file_specification
The left-hand side of a client view mapping is called the depot side; 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. But views can contain multiple mappings, and can be much more complex. All client views, no matter how elaborate, perform the same two functions:

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 will be identical on both sides.

In the client view

//depot/elm_proj/...       //eds_elm/...
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 will be mapped to the client workspace file //eds_elm/nls/gencat/README.

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/elm-help.1 will be found on the client host in /usr/edk/elm/doc/elm-help.1.

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

//depot/...  //eds_elm/...
would 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; most users only need to see a subset of the files in the depot. As we've seen, mappings don't need to be direct; by changing the View field, it's possible to map only part of a depot to a client workspace. It's 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.

Mapping the Full Client to only Part of the Depot

Usually only a portion of the depot is of interest to a particular client. The left-hand side of the View field can be changed to point to only the portion of the depot that's relevant.

Bettie is rewriting the documentation for Elm, which is found in the depot within it's 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/...

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

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

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:
//depot/... //mike_elm/...
//depot/elm_proj/doc/elm-help.* //mike_elm/help/elm-help.*

Any file in the depots 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. This view will also work when copying files from client workspace to the depot.

Excluding Files and Directories from the View

Files and directories can be excluded from a client workspace with exclusionary mappings; simply prefacing a mapping with a minus sign ( - ). Whitespace is not allowed between the minus sign and the mapping.

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:
//depot/elm_proj/... //billm/...
-//depot/elm_proj/doc/... //billm/doc/...

Since later mappings take 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 be Different
than Depot Filenames

Mappings can be used to make the names of files different in the client workspace than they are in the depot.

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:
//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 n-th wildcard in the depot specification corresponds to the n-th wildcard in the client description.

The Mapped Strings Can Be Rearranged

The %d wildcard can be used to rearrange the order of the matched substrings.

Mike wants to change the names of any files with a dot in them in such a way that the file's suffixes and prefixes are reversed within his client workspace. For example, he'd like to call the Ref.guide file in the depot guide.Ref in his client workspace. (Mike can be a bit difficult to work with). He uses the following mappings:
//depot/elm_proj... //mike_elm/...
//depot/elm_proj/%1.%2 //mike_elm/help/%2.%1

Two Mappings Can Conflict and Fail

It is possible for multiple mappings in a single view to lead to a situation in which the name does not map the same way in both directions. When a file doesn't map the same way in both directions, the file is ignored.

Joe has constructed a mapping as follows:
//depot/elm_proj/... //joe/elm/...
//depot/nowhere/* //joe/elm/doc/*

The file //depot/elm_proj/doc/help would map via the first line to
//joe/elm/doc/help, but the same file in the client workspace would map back 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.

Referring to Files on Command Lines

Any file names given as arguments in a perforce command can be referred in one of two ways: by using the name of the file in the client workspace, or by using the name of the file in the depot. When using the name of the file in the client workspace, the user may give the name in either local or depot syntax.

Local Syntax

Local syntax is simply the file's name as specified by the client's 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 (i.e. it doesn't allow sub/dir/./here/foo.c).

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

The specifier //... is occasionally used; it means `all files in all depots'.

Providing Files as Arguments to Perforce 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 determine which is the corresponding file in the depot. If a depot filename is given, the client view determines which is the corresponding file in the client.

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

· While in his client root directory, he could type

p4 edit src/lock.c
· While in the src subdirectory, he could type

p4 edit lock.c
· While in any directory on the client host, he can type

p4 edit //eds_elm/src/lock.c
or

p4 edit //depot/elm_proj/src/lock.c
or

p4 edit /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.

The main 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 remainder of this manual will use these syntaxes interchangably throughout the example set.

Wildcards and Perforce Syntax

perforce's wildcards may be mixed with both local or perforce syntax. For example:
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 weasel
//depot/... All files in the depot

The "*" wildcard is used the same way in perforce syntax, all UNIX command shells, and most other command shells. Normally, the shell will match "*" against the contents of the client directory; to have perforce match the "*" 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'

There is one case in which the "..." wildcard cannot be used, and that is with the p4 add command. The "..." wildcard is expanded by the p4d server, and since the server doesn't know what files you're adding (after all, they're not in the depot yet), it can't expand that wildcard. The "*" wildcard can be used with p4 add; in this case, it is expanded by the local OS shell, not by the p4d server.

File Names

Because of perforce's naming conventions, certain characters cannot be used in file names. These include unprintable characters, the above wildcards, and the perforce revision characters @ and #.

Specifying Older File Revisions

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

Revision
Specification

Meaning

Examples

file#n Revision number lock.c#3 Refers to revision 3 of file lock.c
file@n A change number lock.c@126 Refers to the version of lock.c when changelist 126 was submitted, even if it was not part of the change.
//depot/...@126 Refers to the state of the whole depot at changelist 126
file@label A label name. lock.c@beta. The revision of lock.c in the label called beta
file@client A client name. E.g. ola.c@joe. This refers to the revision of ola.c last taken into client workspace joe. lock.c@lisag The revision of lock.c last taken into client workspace lisag
file#none The nonexistent revision. 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. 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. lock.c#have Synonymous with
lock.c@clientname where clientname is the name of the current client.

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 file that doesn't exist at all.

A revision specification can be given without a file name. 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 revision of all files in the depot, and @label refers to the revisions of all files in the named label.

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

p4 get //edk/doc/*@30
Later, he sets up another client for a different user. The new client should have all of the file revisions that Ed last got. Ed sets up the new client specificatioin and types

p4 get //depot//elm_proj/...@edk
He could have typed

  p4 get @edk
and the effect would have been the same.

Another client needs all its files deleted, but wants to perforce to know that it still has these files. Ed types

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

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 beginning is left at 1.

If no revision number or range is given where a revision range is expected, the default is all revisions.

File Types

perforce supports normal text files as well as binary, "large text" files, keyword text files, Macintosh resource forks, and symbolic links. perforce attempts to find the type of the file automatically: when you p4 add a file, perforce first determines if the file is a regular file or a symbolic link, and then examines the first part of the file to try to determine whether is it text or binary. If it finds any non-text characters, the file is considered binary; otherwise, the file is considered text.

The detected file type can be overridden by using p4 add -t type, where type is one of binary, text, ltext, xbinary, xtext, ktext, kxtext, resource or symlink. Descriptions of these file types are given below.

A file's type are inherited from one revision to the next. A file can be opened with a different type for the new revision with p4 edit -t type. If a file has already been opened with p4 add or p4 edit, its type can be changed with p4 reopen -t type.

perforce must sometimes store the complete version of every file in the depot, but most often it stores only the changes in the file since the previous revision. This is called delta storage, and perforce uses RCS format to store its deltas. Whether full file or delta storage is used is determined by the file type. 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.

The perforce file types are:

Keyword

Description

Comments

Storage
Type

text Text file Treated as text on the client delta
xtext Executable text file Like a text file, but execute permission is set on the client file. delta
binary Non-text file Accessed as binary files on the client full file
xbinary Executable binary file Like a binary file, but execute permission is set on the client file. full file
ltext Long text file This type should be used for generated text files, such as PostScript. full file
symlink Symbolic link UNIX clients access these as symbolic links; non-UNIX clients treat them as (small) text files delta
ktext Text file with keyword expansion. Any inclusion of the literal string $Id:$ within the file will be expanded to reflect the depot file name and revision number. delta
kxtext Executable text file with keyword expansion Like a ktext file, but execute permission is set on the client file delta
resource Macintosh resource fork Please see the Macintosh client release notes at <http://www.perforce.com/perforce/doc/macnotes.txt> full file

To find the type of an existing file, use the p4 opened reporting command.

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 EDITOR. 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 by a tabstop on the lines below 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 command reference in this manual.

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 these commands can take a file specifier, with or without wildcards, to limit reporting to those files that match the arguments on the command line. Without the file specifier, the reports are generated for all files.

These reports always generated information on depot files, not files in 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 get -n Tells you what p4 get 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 input.
p4 where For each file in the client, shows the location in the depot of the corresponding 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.


[Top] [Prev] [Next]

[email protected]
Copyright © 1997, Perforce Software. All rights reserved.