Perforce 2004.2 User's Guide


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

Chapter 6
Perforce Basics:
Miscellaneous Topics

So far, this manual has provided an introduction to the basic functionality provided by Perforce. Subsequent chapters cover the more advanced features. Included here is information on the following miscellaneous topics likely to be encountered while working with Perforce:

Using passwords and logging in and out of Perforce,
Controlling your Perforce environment with the P4CONFIG environment variable,
Command-line flags common to all p4 commands,
How to work on files while not connected to a Perforce server,
Renaming files, and
Recommendations for organizing files within the depot.

Perforce Passwords

Without passwords, any user can assume the identity of any other Perforce user by setting the value of P4USER to a different username, either by using the -u flag with the p4 command, or by setting P4USER in a P4CONFIG configuration file. To improve security and accountability, use passwords.

Setting passwords

To prevent someone else from impersonating you within Perforce, set a password with the p4 passwd command. No one, including the user who set the password, will be able to use any Perforce commands under your username without providing the password to Perforce.

Your system administrator may have configured your Perforce server to require "strong" passwords. A password is considered strong if it is at least eight characters long, and at least two of the following are true:

Password contains uppercase letters
Password contains lowercase letters
Password contains non-alphabetic characters.

For example, the passwords a1b2c3d4, A1B2C3D4, aBcDeFgH are considered strong.

Be careful when setting passwords. If you forget your password after having set it, a Perforce superuser will have to reset or remove your password for you.

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

Perforce passwords and authentication

To authenticate to a Perforce server with a password, set your password with p4 passwd, and use the password with every Perforce command you run. To use the password you have set, either:

set the value of the environment or registry variable P4PASSWD to your password, or
set the value of P4PASSWD within the file described by P4CONFIG, or
use the -P password flag between p4 and the actual command when calling Perforce commands (for instance, p4 -P mypassword submit).

If you are using ticket-based authentication, changing your password automatically logs out all of your existing tickets.

Perforce tickets: logging in and out

In addition to password-based authentication, Perforce supports ticket-based authentication. Because ticket-based authentication does not rely on environment variables or command-line flags, it is more secure than password-based authentication, and your system administrator may have configured your server to require its use.

Tickets are stored in a file in your home directory. After you have logged in, your ticket is valid for a limited period of time (by default, 12 hours). Your administrator may have changed this setting. By default, your ticket is valid only for the IP address of the workstation from which you logged in, but you can create tickets that are valid for any IP address if you are working from more than one machine and using a shared home directory.

To use ticket-based authentication, set a password with p4 passwd, and log in by getting a ticket from the Perforce server by using the p4 login command.

p4 login Enter your password at the prompt. If you log in successfully, a ticket is created for you in the ticket file in your home directory, and you are not prompted to log in again until either your ticket expires (by default, in 12 hours), or until you log out of Perforce.

To extend a ticket's lifespan, run p4 login while already logged in. Running p4 login while already logged in extends your ticket's lifespan by 1/3 of its initial timeout period, subject to a maximum of its initial timeout period.

If you are in an environment where you are using Perforce from more than one machine while sharing a home directory (for example, many UNIX environments), log in with:

p4 login -a Using p4 login -a creates a ticket in your home directory that is valid from all IP addresses, enabling you to remain logged in to Perforce from more than one workstation.

To see if your ticket is still valid, use:

p4 login -s If your ticket is valid, the length of time for which it will remain valid is displayed.

To log out of Perforce by deleting your ticket, use:

p4 logout If you are logged in from more than one machine at once, you can log out from all machines simultaneously by invalidating your ticket with:

p4 logout -a For more information, see the Command Reference.

Reconfiguring the Perforce Environment with $P4CONFIG

Some Perforce users have multiple client workspaces, each of which can connect to a different Perforce server. There are three ways you can change 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, and so on, 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`	`P4USER`	`P4CHARSET`
`P4PORT`	`P4MERGE`	`P4PASSWD`	`P4HOST`	`P4LANGUAGE`

Example:

Using P4CONFIG to automatically reconfigure the Perforce environment

Ed often switches between two workspaces on the same machine. 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 sets the P4CONFIG environment variable to .p4settings. He creates a file called.p4settings in /usr/edk/elm containing the following text:

He creates a second .p4settings file in /usr/edk/other/graphics. It contains:

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

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

The P4CONFIG variable is particularly useful if you use multiple client workspaces on the same workstation, because it automates the process of changing the Perforce environment variables whenever you switch your current working directory from one client workspace directory to another.

Command-Line Flags Common to All Perforce Commands

Some 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. The flags are as follows:


Flag	Meaning	Example
`-c clientname`	Runs the command on the specified client. Overrides the `P4CLIENT` environment variable.	`p4 -c joe edit //depot/file.c` Opens file `file.c` for editing under client workspace `joe`.
`-C charset`	For servers in unicode mode, override the `P4CHARSET` variable.	`p4 -C utf8 print //depot/file`
`-d directory`	Specifies the current directory, overriding the environment variable `PWD`.	`p4 -d ~elm/src edit one two` Opens files `one` and `two` for edit; these files are found relative to `~elm/src`.
`-G`	Cause all output (and batch input for form commands using the `-i` option) to be formatted as marshalled Python dictionary objects	`p4 -G info`
`-H host`	Specify the host name, overriding the environment variable `P4HOST`.	`p4 -H host print //depot/file`
`-L language`	For servers with non-English error messages, override the `P4LANGUAGE` variable.	Reserved for system integrators.
`-p server`	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.
`-s`	Prepend a tag to each line of output so as to make output more amenable to scripting.	`p4 -s info`
`-u username`	Specifies a Perforce user, overriding the `P4USER` environment variable. The user can run only those commands to which he or she has access.	`p4 -u bill user` Presents the `p4 user` form to edit the specification for user `bill`. The command works 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 "Working Detached" on page 84.
`-V`	Displays the version of the `p4` executable.	`p4 -V`

All Perforce commands can take these flags, even commands for which these flag usages are useless (for instance, p4 -u bill -d /usr/joe help). Other flags are available as well; these additional flags are command dependent. See the Perforce Command Reference or use p4 help commandname to see the flags for each command.

Working Detached

Under normal circumstances, you work in your client workspace with a functioning network connection to a Perforce server. As you edit files, you announce your 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 your client workspace.

If it is not possible to have network connectivity to the server for prolonged periods of time, you will need a method for working while detached from the server. Use the following techniques to work detached:

Work on files without using Perforce commands. Instead, use native OS commands to manually change the permissions on files, and then edit or delete the files.
If you did not edit the files within a client workspace, copy the files to the client workspace when the network connection is reestablished.
Use p4 diff to find the files in your workspace that have changed or been added without Perforce's knowledge (that is, without the use of Perforce commands). Use the output from p4 diff to bring the depot in sync with the client workspace.

Finding changed files

Use the p4 diff reporting command to compare a file in the client workspace with the corresponding file in the depot. The behavior of p4 diff 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.

Updating the depot with changed files

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 does not 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 file deletion command.

For example, suppose that you accidentally delete a client workspace file with the UNIX rm command, and that the file is one that you wanted to keep. Even after a submit, p4 have still lists the file as being present in the workspace.

In such a situation, you can 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.

Renaming Files

Although Perforce doesn't have a rename command, you can rename files 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 is moved to the directory and renamed according to the to_file specifier. For example, if from_file is d1/one and to_file is d2/two, then one is moved to the d2 directory, and is renamed two. The from_file and to_file specifiers can include wildcards, as long as they are matched on both sides. Perforce write access (explained in the Perforce System Administrator'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 (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.

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 looks 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 workspace 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 zeus, athena, and apollo, three subtrees might be created within the depot: //depot/zeus, //depot/athena, and //depot/apollo. If Joe is working on the zeus project, his mapping might look like this:


`//depot/zeus/... //joe/...`

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


`//depot/athena/... //sarah/athena/... //depot/apollo/... //sarah/apollo/...`

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

Another way of solving the same problem is to have the Perforce system administrator create one depot for each project or branch. See the Perforce System Administrator's Guide for details about setting up multiple depots.