| Perforce 2004.2 User's Guide | ||
|
<< Previous Chapter Perforce Basics: Quick Start |
Table of Contents Index Perforce on the Web |
Next Chapter >> Perforce Basics: Resolving File Conflicts |
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:
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.
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 |
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. |
//depotname/file_specification
The right-hand side of each mapping specifies one or more files or directories in a client workspace, and has the form:
//clientname/file_specification
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:
//depot/... //clientname/...
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.
|
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.
//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 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.)
//depot/... //eds_elm/...
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.
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 are mapped to /usr/bes/docs. Files not beneath the
//depot/elm_proj/doc directory no longer appear in Bettie's workspace.
The elm_proj subdirectory of the depot contains a directory called doc, which has all of the
Elm documents. Included in this directory are four files named elmdoc.0 through
elmdoc.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, which is located at
the same level as his doc directory. The four elmdoc files will go here, so he fills in the View:
field of the p4 client form as follows:
Any file whose name starts with elmdoc within the depot's doc subdirectory is caught by the
later mapping and appears in Mike's workspace's help directory; all other files are caught by
the first mapping and appear in their normal location. Conversely, any files beginning with
elmdoc within Mike's client workspace help subdirectory are mapped to the doc
subdirectory of the depot.
|
Note |
Whenever you map two sections of the depot to different parts of the client workspace, some depot and client files will remain unmapped. See "When two mappings conflict" on page 43 for details. |
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:
Because later mappings have precedence over earlier ones, no files from the depot's doc
subdirectory are copied into Bill's workspace. Conversely, if Bill has a doc subdirectory in his
client, no files from that subdirectory are ever copied to the depot.
Mike wants to store the files as above, but he wants to take the elmdoc.X files in the depot
and call them helpfile.X in his client workspace. He uses the following mappings:
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.
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. He uses the following mappings:
Joe has constructed a view as follows:
The second mapping //depot/proj2/... maps to //joe/project, and conflicts with the
first mapping. Because these mappings conflict, the first mapping is ignored; no files in
//depot/proj1 are mapped into the workspace: //depot/proj1/file.c is not mapped,
even if //depot/proj2/file.c does not exist.
Joe has constructed a view as follows:
The overlay mapping +//depot/proj2/... maps to //joe/project, and overlays the
first mapping. Overlay mappings do not conflict. Files in //depot/proj2 take precedence
over files in //depot/proj1: if //depot/proj2/file.c is missing,
//depot/proj1/file.c is mapped into the workspace instead.
Overlay mappings are often useful for applying sparse patches within the context of build environments.
|
View: |
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.
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:
|
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:
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 |
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.
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.
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 |
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.
Ed wants to delete the src/lock.c file. He can issue the required p4 delete command in a
number of ways:
From his client root directory, he could type
or, while in the src subdirectory, he could type
or, while in any directory on his workstation, he could type any of the following commands:
p4 delete //eds_elm/src/lock.c
p4 delete //depot/elm_proj/src/lock.c
p4 delete /usr/edk/elm/src/lock.c
You can provide filenames to any Perforce command in client syntax, depot syntax, or local
syntax. The examples in this manual use all three syntax forms interchangeably.
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.
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:
To add a file such as [email protected], force a literal interpretation of special characters by using:
p4 add -f //depot/path/[email protected]
When you submit the changelist, the characters are automatically expanded and appear in the change submission form as follows:
//depot/path/status%40june.txt
After submitting the changelist with the file's addition, you must use the ASCII expansion in order to sync the file to your workspace or edit it within your workspace. For example:
p4 sync //depot/path/status%40june.txt
Most special characters tend to be difficult to use in filenames in cross-platform environments: UNIX separates path components with /, while many DOS commands interpret / as a command line switch. Most UNIX shells interpret # as the beginning of a comment. Both DOS and UNIX shells automatically expand * to match multiple files, and the DOS command line uses % to refer to variables.
p4 edit //depot/path/status%40june.txt
"//depot/release 1.2/doc/..." "//eds_ws/1.2 documentation/..."
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.
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.
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.
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 |
Refers to revision 3 of file lock.c |
|
file@changenum |
A change number |
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 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 |
The revision of lock.c in the label called beta (labels are explained in Chapter 8, Labels). |
|
file@clientname |
The revision of file last taken into client workspace clientname. |
The revision of lock.c last taken into client workspace lisag_ws |
|
file#none |
The nonexistent revision. |
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. |
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. |
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. |
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" 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.
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:
Lisa wants to populate her client workspace with the file revisions that Ed last synced to his
workspace. She types:
p4 sync //depot/elm_proj/doc/...@eds_elm
All files in //depot/elm_proj/doc/... are synced to Lisa's workspace at the revisions at
which they were last synced to Ed's workspace: in this case, as of the submission of changelist
30.
Ed wants to remove all Perforce-controlled files from his client workspace. He types:
All files in his client workspace that are managed by Perforce are removed from his workspace
("synced to the nonexistent revision"), but are not removed from the depot.
The commands that accept revision range specifications are:
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).
A release manager needs to see a list of all changes to the Elm project in July, and types:
p4 changes //depot/elm_proj/...@2000/7/1,2000/8/1
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 build w/bug fix'
...
Change 673 on 2000/07/31 by edk@eds_elm 'Final build for QA'
The manager can then use p4 describe change against any desired changelist number to
obtain a full description.
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:
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, and occurs during the submission process, and decompression happens while syncing. The client workspace always contains the file as it was submitted to the depot.
|
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, |
|
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, |
|
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, |
|
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 |
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.
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.
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.
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.
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:
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.
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 2004.2 User's Guide | ||
|
<< Previous Chapter Perforce Basics: Quick Start |
Table of Contents Index Perforce on the Web |
Next Chapter >> Perforce Basics: Resolving File Conflicts |