99.1 Perforce p4 User Guide: Superuser Commands and Flags

Perforce 99.1 p4 User's Guide


<< Previous Chapter Editing Job Specifications	Table of Contents Index Perforce on the Web	Next Chapter >> Environment Variables

Chapter 16
System Administration: Superuser Commands and Flags

Three Perforce commands can be used only by users with Perforce superuser privileges. These commands allow the superuser to verify files using 128-bit signatures, remove all traces of file from the depot, create multiple depots on the local server, limit the number results of user commands, or provide read access to files on other servers. Additionally, a special flag (-f) available with certain commands allows the superuser to perform operations unavailable to ordinary users.

File Verification by Signature

The p4 verify filenames command can be used to generate 128-bit signatures of each revision of the named files. A list of signatures generated by p4 verify can later be used to confirm proper recovery in case of a crash: if the signatures of the recovered files match the previously saved signatures, the files were recovered accurately.

To save file revisions' signatures in the Perforce database, use the -u flag. Subsequent verifications will be compared against the stored signatures; if a new signature does not match the signature in the Perforce database for that file revision, Perforce adds the characters BAD! after the signature.

File Obliteration

The depot is always growing. Obviously, this is not always desirable: a branch might be performed incorrectly, creating hundreds of unneeded files; or perhaps there are simply a lot of old files around that are no longer being used. p4 delete won't help, since this command marks the file as deleted in its head revision, but leaves the old revisions intact.

p4 obliterate filename can be used by superusers to remove all traces of a file from a depot, making the file indistinguishable from one that never existed in the first place. p4 obliterate is so destructive, in fact, that we haven't even told you how it really works yet. p4 obliterate filename only reports on what it will do; to actually destroy the files, use p4 obliterate -y filename.

Changelist Deletion & Description Editing

The -f flag can be used with p4 change to change the description or username of submitted changelists. The syntax is p4 change -f changenumber; this presents the standard changelist form, in which the description and/or username may be edited.

The -f flag can also be used to delete any submitted changelists that have been emptied of files with p4 obliterate. The full syntax is p4 change -d -f changenumber.

Server Swamp Prevention

When the depot becomes quite large, certain commands can swamp the server, substantially slowing down other users' operations. For example, if p4 sync is typed, Perforce will attempt to sync all the files in the client workspace from the depot.

The Perforce superuser can limit the number of files that particular users are allowed to operate on within a single command. To do this, use the Maxresults: field in the p4 group form. The number in this field specifies the maximum number of rows of data that can be operated on within a single command. If a user is listed in multiple groups, the highest of the maxresults value for those groups is taken as the user's maxresults value.

If the user attempts an operation that exceeds his maxresults value, the entire operation will fail, and the user will need to attempt it again using more restrictive parameters. For example, if the user has attempted to sync more files then his maxresults value allows, he can retry the sync by providing a more restrictive file specification, such as p4 sync //depot/build/... .

To unlimit the number of result lines processed for a particular group, set the Maxresults: value for that group to unlimited.

Since maxresults values can make life difficult for your users, do not use them unless you find that certain operations are slowing down your server. The Maxresults: value should never be less than 10K, since certain behind-the-scene operations performed by P4Win, the Perforce Windows GUI, may require a 5K - 8K Maxresults: value.

Distributed Depots

Perforce distributed depots allow the p4 client program to access files from multiple depots. These other depots may reside within the p4d server normally accessed by the p4 client program, or they may reside within other, remote, p4d servers.

The p4 client's local p4d server program acts as a proxy client to the remote server programs, so the client doesn't need to know where the files are actually stored, and doesn't need direct access to the remote p4d server programs.

The use of distributed depots on remote servers is currently limited to read-only operations; thus, a p4 client program may not add, edit, delete or integrate files that reside in depots on other servers. Depots sharing the same p4d server as the client are not subject to this limitation.

Defining New Depots

New depots in a server namespace are defined with the command p4 depot depotname. If called with the default depotname depot, the p4 depot command will bring up the following form:


`Depot Name: depot` `Type: local` `Address: subdir` `Map: depot/...`

When p4 depot depot is called, the form is filled in with values representing the state of the default depot. Its name, of course, is depot. It resides in the local p4d server namespace; so its type is local, (as opposed to remote). The Map: field indicates where the depot subdirectory is located relative to the root directory of the p4d server program; in this default case, the depot called depot starts in the depot subdirectory directly underneath the root.

Defining Local Depots

To define a new local depot (that is, a new depot in the current p4d server program namespace), p4 depot is called with the new depot name, and only the Map: field in the resulting form need be changed. For example, to create a new depot called book with the files stored in the local p4d server namespace in a root subdirectory called manual, the command p4 depot book would be typed, and the resulting form would be filled in as follows:


`Depot Name: book` `Type: local` `Address: subdir` `Map: manual/...`

Defining Remote Depots

Defining a new depot on a remote p4d server is only slightly more complicated. The Type: is remote; the server address must be provided in the Address: field, and the Map: field must be given a mapping into the remote depot namespace.

Example

Defining a remote depot

Lisa is working on a GUI for Elm. She and Ed are using different p4d servers; his is on host pine, and it's listening on port 1818. Lisa wants to grab Ed's GUI routines for her own use; she knows that Ed's color routine files are located on his p4d server's single depot under the subdirectory graphics/GUI. Lisa's first step towards accessing Ed's files would be to create a new depot. She'll call this depot gui; she'd type p4 depot GUI and fill in the form as follows:

Depot Name: gui
Type: remote
Address: pine:1818
Map: //depot/graphics/gui/...

This creates a remote depot called gui on Lisa's p4d server; this depot maps to Ed's depot's namespace under its graphics/gui subdirectory.

The Mapping Field, and What it Means

The Map: field is analogous to a client's view, except that the view may contain multiple mappings and the Map: field always contains a single mapping. This single mapping format changes depending on whether or not the depot being defined is local or remote:

If a local depot is being defined, the mapping should contain a subdirectory relative to the file space of the p4d server root directory. For example, graphics/gui/... maps to the graphics/gui subdirectory of the p4d server root.
If a remote depot is being defined, the mapping should contain a subdirectory relative to the remote depot namespace. For example, //depot/graphic/gui/... would map to the graphic/gui subdirectory of the remote server depot named depot.

Note that the mapping subdirectory must always contains the "..." wildcard on its right side.

Naming Depots

Depot names share the same namespace as branches, clients, and labels. For example, //foo refers unambiguously to either the depot foo, the client foo, the branch foo, or the label foo.

Accessing Files In Other Depots

Files from any remote or local depot known to the default p4d server can be accessed simply by using the depot's name wherever the default depot name depot is usually used. This means that any defined depot name can be used in the following ways:

As part of any p4 command that takes depot syntax. For example, the following command will retrieve all files in the subdirectory foo of depot bar:
p4 sync //bar/foo/...
On the left-hand side of any client view. For example, if the p4 client form is filled in as follows on client spice, any files from the local depot depot will be mapped to /usr/jake/src/local, and any files from the remote depot foo will be mapped to /usr/jake/src/remote.

Client: spice
Description:
Created by Jake.
Root: /usr/jake/src
View:
//depot/... //spice/local/...
//foo/... //spice/remote/...
On the left-hand side of any branch or label view, in the same way the mapping has been provided in the above client view.

There is one, rather large, exception to these rules: although files from other local depots can be used in any operation, files from remote depots can be used only in read-only operations. Thus, no files can ever be used in a p4 submit to a remote depot.

Additionally, files from remote depots can't be used in p4 filelog or p4 describe, even though these operations are read-only.

Integrating Files From Other Depots

A branch view may contain remote files in its mappings, so that files can be branched and later integrated from a remote depot into the local one. This works much as local branching and integration do, with two exceptions:

When remote files are integrated for the first time (i.e. they don't exist locally), they are opened for import rather than branch. The difference between import and branch is only that, upon submission, the remote files are copied locally. Normally, branch performs a "lazy copy", referring to the source file/revision until a new revision is submitted. Import copies the contents of the source file/revision to the local target.
Since it is not possible to make remote files the targets of integration, integrations are one-way only, from remote to local.

Limiting Access from Other Servers

Remote depots are always accessed by a virtual user named remote, and by default, all the files on any Perforce server may be accessed remotely. To limit or eliminate remote access to a particular server, use p4 protect to set permissions for user remote on that server. For example, to eliminate remote access to all files in all depots on a particular server, set the following permission on that server:

Since remote depots can only be used for read access, it is not necessary to remove write or super access.

The virtual user remote does not consume a Perforce license.

Deleting Depots

Depots may be deleted with p4 depot -d depotname.

Depot Reporting Commands

All depots known to the current p4d server can be listed with the p4 depots command.

Forcing Operations with the -f Flag

Certain commands allow the superuser to use the -f flag to force certain operations unavailable to ordinary users. This flag can be used with p4 branch, p4 change, p4 client, p4 job, p4 label, and p4 user. The usages and meanings of this flag are as follows:


Command	Syntax	Function
`p4 branch`	`p4 branch -f branchname`	Allows modification date to be changed while editing the branch specification
`p4 branch`	`p4 branch -f -d branchname`	Deletes the branch, ignoring ownership
`p4 change`	`p4 change -f [changelist#]`	Allows modification date to be changed while editing the changelist specification
`p4 change`	`p4 change -f changelist#`	Allows description field and username in a committed changelist to be edited
`p4 change`	`p4 change -f -d changelist#`	Deletes empty, committed changelists
`p4 client`	`p4 client -f clientname`	Allows modification date to be changed while editing the client specification
`p4 client`	`p4 client -f -d clientname`	Deletes the client, ignoring ownership, even if the client has opened files
`p4 job`	`p4 job -f [jobname]`	Allows manual update of read-only fields
`p4 label`	`p4 label -f labelname`	Allows modification date to be changed while editing the label specification
`p4 label`	`p4 label -f -d labelname`	Deletes the label, ignoring ownership
`p4 user`	`p4 user -f username`	Allows update of all fields, ignoring ownership
`p4 user`	`p4 user -f -d username`	Deletes the user, ignoring ownership.

Perforce 99.1 p4 User's Guide


<< Previous Chapter Editing Job Specifications	Table of Contents Index Perforce on the Web	Next Chapter >> Environment Variables

Please send comments and questions about this manual to [email protected].
Copyright 1997, 1999 Perforce Software. All rights reserved.
Last updated: September 15, 1999. Manual version 99.1.ug.4.