Perforce 2009.1: Command Reference

p4 client

Synopsis

Create or edit a client workspace specification and its view.

Syntax

p4 [g-opts] client [-f -t template] [clientname]
p4 [g-opts] client -o [-t template] [clientname]
p4 [g-opts] client -d [-f] clientname
p4 [g-opts] client -i [-f]

Description

A Perforce client workspace is a set of files on a user's machine that mirror a subset of the files in the depot. The p4 client command is used to create or edit a client workspace specification; invoking this command displays a form in which the user enters the information required by Perforce to maintain the client workspace.

Although there is always a one-to-one mapping between a client workspace file and a depot file, these files do not need to be stored at the same relative locations, nor must they have the same names. The client view, which is specified in the p4 client form's View: field, specifies how files in the client workspace are mapped to the depot, and vice-versa.

When called without a clientname argument, p4 client operates on the client workspace specified by the P4CLIENT environment variable or one of its equivalents. If called with a clientname argument on a locked client, the client specification is read-only.

When p4 client completes, the new or altered client workspace specification is stored within the Perforce database; the files in the client workspace are not touched. The new client view doesn't take effect until the next p4 sync.

The command p4 workspace is an alias for p4 client.

Form Fields

Field Name	Type	Description
Client:	Read-only	The client workspace name, as specified in the P4CLIENT environment variable or its equivalents.
Owner:	Writable	The Perforce user name of the user who owns the client workspace. The default is the user who created the client workspace.
Update:	Read-only	The date the client workspace specification was last modified.
Access:	Read-only	The date and time that any part of the client workspace specification was last accessed by any Perforce command.
Host:	Writable, optional	The name of the host machine on which this client workspace resides. If included, operations on this client workspace can be run only from this host. The hostname must be provided exactly as it appears in the output of p4 info when run from that host. This field is meant to prevent accidental misuse of client workspaces on the wrong machine. It doesn't provide security, since the actual value of the host name can be overridden with the -H flag to any p4 command, or with the P4HOST environment variable. For a similar mechanism that does provide security, use the IP address restriction feature of p4 protect.
Description:	Writable, optional	A textual description of the client workspace. The default text is Created by owner.
Root:	Writable, mandatory	The directory (on the local host) relative to which all the files in the View: are specified. The default is the current working directory.
AltRoots:	Writable, optional	Up to two optional alternate client workspace roots. Perforce client programs use the first of the main and alternate roots to match the client program's current working directory. This enables users to use the same Perforce client specification on multiple platforms with different directory naming conventions. If you are using a Windows directory in any of your client roots, you must specify the Windows directory as your main client root and specify your other client root directories in the AltRoots: field. For example, an engineer building products on multiple platforms might specify a main client root of C:\Projects\Build for Windows builds, and an alternate root of /staff/userid/projects/build for any work on UNIX builds.
Options:	Writable, mandatory	A set of seven switches that control particular client options. See the Usage Notes, below, for a listing of these options.
SubmitOptions:	Writable, mandatory	Flags to govern the default behavior of p4 submit. • submitunchanged All open files (with or without changes) are sub­mitted to the depot. This is the default behavior of Perforce. • submitunchanged+reopen All open files (with or without changes) are sub­mitted to the depot, and all files are automatically reopened in the default changelist. • revertunchanged Only those files with content or type changes are submitted to the depot. Unchanged files are reverted. • revertunchanged+reopen Only those files with content or type changes are submitted to the depot and reopened in the default changelist. Unchanged files are reverted and not reopened in the default changelist. • leaveunchanged Only those files with content or type changes are submitted to the depot. Any unchanged files are moved to the default changelist. • leaveunchanged+reopen Only those files with content or type changes are submitted to the depot. Unchanged files are moved to the default changelist, and changed files are reopened in the default changelist. This option is similar to submitunchanged+reopen, except that no unchanged files are submitted to the depot.
LineEnd:	Writable, mandatory	A set of four switches that control carriage-return/linefeed (CR/LF) conversion. See the Usage Notes, below, for a listing of these options.
View:	Writable, multi-line	Specifies the mappings between files in the depot and files in the client workspace. See Views for more information.

Options

-t clientname	Copy client workspace clientname's view and client options into the View: and Options: field of this client workspace. (i.e, use clientname's View: as a template)
-f	Allows the last modification date, which is normally read-only, to be set. Administrators may use this flag to delete or modify locked workspaces owned by other users.
-d clientname	Delete the specified client workspace, if the client is owned by the invoking user or it is unlocked. (The -f flag allows allows Perforce superusers to delete locked client workspaces that they don't own.)
-i	Read the client description from standard input.
-o	Write the client specification to standard output.
g-opts	See the Global Options section.

Usage Notes

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
N/A	N/A	list

•	Use quotation marks to enclose depot-side or client side mappings of file or directory names that contain spaces.

•	Spaces in client workspace names are translated to underscores. For example, typing the command p4 client "my client" creates a client workspace called my_client.

•	The Options: field contains six values, separated by spaces. Each of the six options have two possible settings; the following table provides the option values and their meanings:

Option	Choice	Default
[no]allwrite	If set, unopened files on the client are left writable. If allwrite is set, this option overrides noclobber.	noallwrite
[no]clobber	If set, a p4 sync overwrites ("clobbers") writable-but-unopened files in the client that have the same name as the newly-synced files. If allwrite is set, the noclobber option is ignored.	noclobber
[no]compress	If set, the data stream between the client and the server is compressed. (Both client and server must be version 99.1 or higher, or this setting is ignored.)	nocompress
[no]crlf	Note: 2000.2 or earlier only! On Windows, if crlf is set, CR/LF translation is performed automatically when copying files between the depot and the client workspace.	crlf
[un]locked	Grant or deny other users permission to edit the client specification (To make a locked client specification truly effective, you should also set a the client's owner's password with p4 passwd.) If locked, only the owner is able to use, edit, or delete the client spec. Perforce administrators can override the lock by using the -f (force) flag with p4 client.	unlocked
[no]modtime	For files without the +m (modtime) file type modifier: • For Perforce clients at the 99.2 level or earlier, if modtime is set, the modification date (on the local filesystem) of a newly synced file is the date and time at the server when the file was submitted to the depot. • For Perforce clients at the 2000.1 level or higher, if modtime is set, the modification date (on the local filesystem) of a newly synced file is the datestamp on the file when the file was last modified. • If nomodtime is set, the modification date is the date and time of sync, regardless of Perforce client version. For files with the +m (modtime) file type modifier: • For Perforce clients at the 99.2 level or earlier, the +m modifier is ignored, and the behavior of mod­time and nomodtime is as documented above. • For Perforce clients at the 2000.1 level or higher, the modification date (on the local filesystem) of a newly synced file is the datestamp on the file when the file was submitted to the depot, regardless of the setting of modtime or nomodtime on the client.	nomodtime (i.e. date and time of sync) for most files. Ignored for files with the +m file type modifier.
[no]rmdir	If set, p4 sync deletes empty directories in a client if all files in the directory have been removed.	normdir

•	By default, any user can edit any workspace specification with p4 client -c clientname. To prevent this from happening, set the locked option and use p4 passwd to create a password for the client workspace owner.

•

The compress option speeds up client/server communications over slow links by reducing the amount of data that has to be transmitted. Over fast links, the compression process itself may consume more time than is saved in transmission. In general, compress should be set for line speeds under T1, and should be left unset otherwise.

•	The LineEnd: field controls the line-ending character(s) used for text files in the client workspace.

Note	The LineEnd: option is new to Perforce 2001.1. It renders the previous convention of specifying crlf or nocrlf in the Options: field obsolete. The behavior of the mutually-contradictory combination of LineEnd: win and Options: crlf is undefined.

The LineEnd: field accepts one of five values:

Option	Meaning
local	Use mode native to the client (default)
unix	UNIX-style (and Mac OS X) line endings: LF
mac	Macintosh pre-OS X: CR only
win	Windows-style: CR, LF.
share	The share option normalizes mixed line-endings into UNIX line-end format. The share option does not affect files that are synced into a client workspace; however, when files are submitted back to the Perforce Server, the share option converts all Windows-style CR/LF line-endings and all Mac-style CR line-endings to the UNIX-style LF, leaving lone LFs untouched. When you sync your client workspace, line endings are set to LF. If you edit the file on a Windows machine, and your editor inserts CRs before each LF, the extra CRs do not appear in the archive file. The most common use of the share option is for users of Windows workstations who mount their UNIX home directories as network drives; if you sync files from UNIX, but edit the files on a Windows machine.

For more information about how Perforce uses the line-ending settings, see Tech Note 63 on the Perforce web site:

http://www.perforce.com/perforce/technotes/note063.html

•

By default, if a directory in the client workspace is empty, (for instance, because all files in the depot mapped to that directory have been deleted since the last sync), a p4 sync operation will still leave the directory intact. If you use the rmdir option, however, p4 sync deletes the empty directories in the client workspace.

If the rmdir option is active, a p4 sync operation may sometimes remove your current working directory. If this happens, just change to an existing directory before continuing on with your work.

•	Files with the modtime (+m) type are primarily intended for use by developers who need to preserve original timestamps on files. The use of +m in a file type overrides the client's modtime or nomodtime setting. For a more complete discussion of the +m modifier, see the File Types section.

•	If you are using multiple or alternate client roots (the AltRoots: field), you can always tell which client root is in effect by looking at the Client root: reported by p4 info.

•	To specify a Perforce client on Windows that spans multiple drives, use a Root: of null, and specify the drive letters in the client workspace view. For instance, the following client spec with a null client root maps //depot/main/... to an area of the C: drive, and other releases to the D: drive:

Client: eds_win Owner:  edk Description:         Ed's Windows Workspace Root:   null Options:        nomodtime noclobber SubmitOptions:  submitunchanged View:         //depot/main/...     "//eds_win/c:/Current Release/..."         //depot/rel1.0/...   //eds_win/d:/old/rel1.0/...         //depot/rel2.0/...   //eds_win/d:/old/rel2.0/...

Use lowercase drive letters when specifying workspaces across multiple drives.

Examples

p4 client	Edit or create the client workspace specification named by the value of P4CLIENT or its equivalents.
p4 client -t sue joe	Create or edit client workspace joe, opening the form with the field values and workspace options in client workspace sue as defaults.
p4 client -d release1	Delete the client workspace release1.

Related Commands

To list client workspaces known to the system	p4 clients
To read files from the depot into the client workspace	p4 sync
To open new files in the client workspace for addition to the depot	p4 add
To open files in the client workspace for edit	p4 edit
To open files in the client workspace for deletion	p4 delete
To write changes in client workspace files to the depot	p4 submit