Perforce Basics: Miscellaneous Topics

Perforce 2000.2 Command Line User's Guide (2000.2.ug.1)


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

Chapter 6
Perforce Basics:
Miscellaneous Topics
The manual thus far has provided an introduction to the basic functionality provided by Perforce, and subsequent chapters cover the more advanced features. In between are a host of other, smaller facilities; this chapter covers these topics. Included here is information on the following:

Changing your Perforce environment with the P4CONFIG environment variable;
Using passwords to prevent impersonation by other users;
Command-line flags common to all Perforce commands;
How to work on files while not connected to a Perforce server;
Refreshing the client workspace;
Renaming files;
Recommendations for organization of files within the depot.

Reconfiguring the Perforce Environment
with $P4CONFIG

Some Perforce users have multiple client workspaces, each of which may connect to a different port. There are three ways of changing your Perforce environment on the fly:

Reset your environment or registry variables each time you want to move to a new workspace;
Use command-line flags (discussed in the next section) to override the value of the environment variables P4PORT, P4CLIENT, and P4USER;
Use the environment variable or registry variable P4CONFIG to point to a file containing a specification for the current Perforce environment.

P4CONFIG names a file (for example, .p4env) that is used to store variable settings. Whenever a Perforce command is executed, the current working directory and its parent directories are searched for a file with the name stored in P4CONFIG. If a file with that name is found, the values of P4PORT, P4CLIENT, etc., are read from that file. If no file of the given name is found, the current values of the Perforce environment variables are used.

Each variable setting in the file stands alone on a line and must be in the form

value

Values that can be stored in the P4CONFIG file are:


`P4CLIENT`	`P4DIFF`	`P4EDITOR`	`P4HOST`
`P4MERGE`	`P4PASSWD`	`P4PORT`	`P4USER`

Example:

Using P4CONFIG to automatically reconfigure the Perforce environment

Ed has two workspaces that he often switches between. The first workspace is elmproj; it has a client root of /usr/edk/elm, and connects to the Perforce server at ida:1818. The second workspace is called graphicwork; its client root is /usr/edk/other/graphics, and it uses the Perforce server at warhol:1666. Ed gives the P4CONFIG environment variable the value .p4settings. He creates a file called .p4settings in /usr/edk/elm; the file contains this text:

He creates a second .p4settings file in /usr/edk/other/graphics; it contains

He always works within the directories his files are located in; when he is anywhere beneath /usr/edk/other/graphics, his Perforce client will be graphicwork, and when he's underneath /usr/edk/elmproj, his client is elmproj.

The values found in the file specified by P4CONFIG will override any environment or registry variables that have been set. Command-line flags (discussed in the next section) will override the values found in the P4CONFIG file.

P4CONFIG automates the process of changing the Perforce environment variables; new settings take effect whenever you switch your current working directory from one client workspace directory to another. If you use multiple client workspaces, this is a very useful feature.

Perforce Passwords

By default, any user can assume the identity of any other Perforce user by setting the value of P4USER to a different username, by using the -u flag with the p4 command, or by setting the value of P4USER configuration within the file described by P4CONFIG. Although this makes it easy to perform tasks for other users when necessary, it can also lead to security problems.

To prevent another user from impersonating you within Perforce, use the p4 passwd command. No one, including the user who set the password, will be able to use any p4 command without providing the password to Perforce. You can provide this password to Perforce in one of three ways:

set the value of the environment or registry variable P4PASSWD to the correct password;
use the -P password flag between p4 and the actual command when giving a Perforce command (e.g., p4 -P eds_password submit);
set the value of P4PASSWD within the file described by P4CONFIG.

For security's sake, the password should always be set while logged onto the server.

Be careful! Once a user's Perforce password has been set by p4 user, there is no way for that user to use Perforce if they forget their password and the value of P4PASSWD has not been properly set. If this happens, the Perforce superuser will have to reset or remove the password.


Note	Passwords can also be created, changed, and deleted via the `p4 user` form.

If you need to your password reset, contact your Perforce administrator. If you are a Perforce administrator, consult the System Administrator's Guide for information on resetting passwords and other common user-related tasks.

Command-Line Flags Common to All
Perforce Commands

Six flags are available for use with all Perforce commands. These flags are given between the system command p4 and the command argument taken by p4. These flags are:


Flag	Meaning	Example
`-c clientname`	Runs the command on the specified client. Overrides the `P4CLIENT` environment variable.	`p4 -c joe edit //depot/foo` Opens file `foo` for editing under client workspace `joe`.
`-d directory`	Specifies the current directory, overriding the environment variable `PWD`.	`p4 -d ~elm/src edit foo bar` Opens files `foo` and `bar` for edit; these files are found relative to `~elm/src`.
`-p server_addr`	Gives the Perforce server's listening address, overriding `P4PORT`.	`p4 -p mama:1818 clients` Reports a list of clients on the server on host `mama`, port `1818`.
`-P password`	Supplies a Perforce password, overriding the value of `P4PASSWD`. Usually used in combination with the `-u` `user` flag.	`p4 -u ida -P idas_pw job` Create a new job as user `ida`, using `ida`'s Perforce password.
`-u username`	Specifies a Perforce user, overriding the `P4USER` environment variable. Only those commands that the specified user has access to on may be run.	`p4 -u bill user` Presents the `p4 user` form to edit the specification for user bill. The command will work without the `-P` flag only if bill has not set a Perforce password.
`-x filename`	Instructs `p4` to read arguments, one per line, from the named file.	See the Working Detached section, directly below.

All Perforce commands can take these flags, even commands for which these flag usages are clearly useless; e.g. p4 -u bill -d /usr/joe help. Other flags are available as well; these additional flags are command dependent. Please consult the Command Reference or use p4 help commandname to find the flags for each command.

Working Detached

Under normal circumstances, users work in their client workspace with a functioning network connection to a Perforce server. As they edit files, they are supposed to announce their intentions to the server with p4 edit, and the server responds by noting the edit in the depot's metadata, and by unlocking the file in the client workspace. However, it is not always possible for a network connection to be present; a method is needed for users to work entirely detached from the server

The scheme is as follows:

The user works on files without giving Perforce commands; instead, OS commands are given that manually change the permissions on files, and then these files are edited or deleted.
If the files were not edited within the client workspace, they should be copied to the client workspace when the network connection is reestablished.
Use p4 diff to find all files in the workspace that have changed or been added without Perforce's knowledge. Output from this command is used to bring the depot in sync with the client workspace.

Finding changed files with "p4 diff"

The p4 diff reporting command is used to compare a file in the client workspace with the corresponding file in the depot. Its behavior can be modified with two flags:


"p4 diff" Variation	Meaning
`p4 diff -se`	Tells the names of unopened files that are present on the client, but whose contents are different than the files last taken by the client with `p4 sync`. These files are candidates for `p4 edit`.
`p4 diff -sd`	Reports the names of unopened files missing from the client. These files are candidates for `p4 delete`.


Note	You can use `p4 edit` on any file, even files you don't want to edit; this command gives the local file write permissions, but does not otherwise alter it.

Using "p4 diff" to update the depot

The p4 diff variations described above can be used in combination with the -x flag to bring the state of the depot in sync with the changes made to the client workspace.

To open changed files for edit after working detached, use


`p4 diff -se > CHANGED_FILES p4 -x CHANGED_FILES edit`

To delete files from the depot that were removed from the client workspace, use


`p4 diff -sd > DEL_FILES p4 -x DEL_FILES delete`

As always, your edit and delete requests are stored in changelists, which Perforce doesn't process until you type p4 submit.

Refreshing files

The process of syncing a depot with a formerly-detached client workspace has a converse: Perforce can get confused about the contents of a client workspace if you accidentally use the local OS deletion command. For example, suppose that you accidently delete a client workspace file via the UNIX rm command, and that the file is one that you wanted to keep. Even after a submit, p4 have will still list the file as being present in the workspace.

Use p4 sync -f files to bring the client workspace in sync with the files the depot thinks you have. This command is mostly a recovery tool for bringing the client workspace back into sync with the depot after accidentally removing or damaging files managed by Perforce.

Recommendations for Organizing the Depot

The default view brought up by p4 client maps the entire depot to the entire client workspace. If the client workspace is named eds_elm, the default view would look like this:

//depot/... //eds_elm/... This is the easiest mapping, and can be used for the most simple Perforce depots, but mapping the entire depot to the workspace can lead to problems later on. Suppose your server currently stores files for only one project, but another project is added later: everyone who has a client workspace mapped as above will wind up receiving all the files from both projects into their workspaces. Additionally, the default view does not facilitate branch creation.

The safest way to organize the depot, even from the start, is to create one subdirectory per project within the depot. For example, if your company is working on three projects named foo, bar, and zeus, three subtrees might be created within the depot: //depot/foo, //depot/bar, and //depot/zeus. If Joe is working on the foo project, his mapping might look like this:


`//depot/foo/... //joe/...`

And Sarah, who's working on the bar and zeus projects, might set up her client workspace as:


`//depot/bar/... //sarah/bar/... //depot/zeus/... //sarah/zeus/...`

This sort of organization can be extended on the fly to as many projects and branches as are needed.

Another way of solving the same problem would be to have the Perforce system administrator create one depot for each project or branch. Please see the Perforce System Administrators Guide for details.


Note	The depot is divided into subdirectories simply by setting up the proper mappings within the client views.

Renaming Files

Although Perforce doesn't have a rename command, a file can be renamed by using p4 integrate to copy the file from one location in the depot to another, deleting the file from the original location, and then submitting the changelist that includes the integrate and the delete. The process is as follows:


`p4 integrate from_files to_files p4 delete from_files p4 submit`

The from_file will be moved to the directory and renamed according to the to_file specifier. For example, if from_file is d1/foo and to_file is d2/bar, then foo will be moved to the d2 directory, and will be renamed bar. The from_file and to_file specifiers may include wildcards, as long as they are matched on both sides. Perforce write access (explained in the Perforce System Adminstrator's Guide) is needed on all the specified files.

Revision histories and renamed files

When you rename a file (or move it from one directory to another) with p4 integrate, you create the new file by creating an integration record that links it to its deleted predecessor.

As a result, if you run p4 changes newfile, you'll see only changes to newfile. Only changes that have taken place after the renaming will be listed:


$ p4 changes newfile.c Change 4 on 2000/10/24 by user@client `Latest bugfix' Change 3 on 2000/10/23 by user@client `Renamed file'

In order to see the full history of changes to the file (i.e., including changes made before the file was renamed or moved), you must specify the -i (include changes from integrations) flag to p4 changes, as follows:


$ p4 changes -i newfile.c Change 4 on 2000/10/24 by user@client `Latest bugfix' Change 3 on 2000/10/23 by user@client `Renamed file' Change 2 on 2000/10/21 by user@client `second version' change 1 on 2000/10/20 by user@client `initial check-in'

Specifying the -i flag tells p4 changes to trace back through the integration records and retrieve all change information, regardless of how many times the file (or the directory in which it lives) has been renamed or moved.