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:

• Command-line flags common to all Perforce commands;
• How to work on files while not connected to a Perforce server;
• Refreshing the client workspace;
• Additional p4 client options;
• Renaming files;
• Flags that allow form data to be read from a file;
• Recommendations for organization of files within the depot.

Command-Line Flags
Common to All Perforce Commands

Five 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 p4d server's listening address, overriding P4PORT.	p4 -p mama:1818 clients Reports a list of clients on the server on host mama, port 1818.
-u username	Specifies a Perforce user, overriding the P4USER, USER, and USERNAME environment variables.	p4 -u bill user Presents the p4 user form to edit specification for user bill. Only those commands that the specified user has permissions on may be run.
-x filename	Instructs p4 to read arguments, one per line, from the named file.	See Working Detached section, below

All Perforce commands can take these flags, even commands for which this flag usage is clearly useless; e.g. p4 -u bill -d /usr/joe help. Other flags are available as well; these additional flags are command dependent. Please use p4 help commandname to find the flags available to 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.
• The p4 diff reporting program is used to find all files in the workspace that have changed 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.

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 delete

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, these edit and delete requests are stored in a changelist, which is not processed until the p4 submit command is given.

Refreshing files

The process of syncing a depot with a formerly-detached client workspace has a converse: it is possible for Perforce to become confused about the contents of a client workspace through the accidental use of UNIX commands. 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.

Just as the process described above will bring the depot in sync with the client workspace, p4 sync -f files can be used 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.

Options in the `p4 client' Form

The form brought up by p4 client has an option field, which takes two values:

Client: eds_elm Owner: ed Description: Created by ed. Root: /usr/edk/elm Options: nomodtime noclobber View: //depot/elm_proj/... //eds_elm/...

The `modtime' option controls the modification times of client files when gotten from the depot with p4 sync or p4 revert. Setting this value to modtime leaves the modification times of files in the client as the times these files were submitted to the depot. If this option is left as the default, nomodtime, the modification date is set to the time the file was copied into the client.

The `clobber' option, which can be set to clobber or noclobber, controls how p4 sync behaves while retrieving files from the depot that already exist in the client. The default, noclobber, tells p4 sync to avoid clobbering client files that aren't open in Perforce but have otherwise been made writable by the user. If clobber is selected, these files will be overwritten.

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, codenamed 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 Chapter 15, page 108, for details.

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 d1 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 is needed on all the specified files. (Perforce access levels are explained in chapter 14.)

Reading Forms from Standard Input;
Writing Forms to Standard Output

Any commands that require the user to fill in a form, such as the p4 client and p4 submit commands, can read the form from standard input with the -i flag. An example is

p4 client -i < filename

where filename contains the field names and values expected by the form. Similarly, the
-o flag can be used to write a form specification to standard output.

The commands that display forms and can therefore use these flags are

	p4 branch		p4 change
	p4 client		p4 job
	p4 label		p4 protect
	p4 submit		p4 user

: