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. More
precisely, it is a named mapping of depot files to workspace files. 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
workspace.

The p4 client command puts the client spec into a
temporary file and invokes the editor configured by the environment
variable P4EDITOR. For new workspaces, the client name
defaults to the P4CLIENT environment variable if set, or to
the current host name. Saving the file creates or modifies the client
spec.

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 workspace are mapped to the depot, and
vice-versa.

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

To submit changes to a stream, you must associate the stream with a
workspace, using the command p4 client -S stream
clientname. To change the stream associated with a
workspace, use the command p4 client -s -S stream
clientname.

Form Fields

Field Name

Type

Description

Client:

Read-only

The client workspace name, as specified in the
P4CLIENT
environment variable or its equivalents.

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

Owner:

Writable, mandatory

The name of the user who owns the workspace. The default is the
user who created the workspace.

The specified owner does not have to be a Perforce user. You
might want to use an arbitrary name if the user does not yet
exist, or if you have deleted the user and need a placeholder
until you can assign the spec to a new user.

Update:

Read-only

The date the workspace specification was last modified.

Access:

Read-only

The date and time that the workspace was last used in any way.
(Note: Reloading a workspace with
p4 reload
does not affect the access time.)

Host:

Writable, optional

The name of the workstation on which this workspace resides. If
included, operations on this client workspace can be run
only from this host. If not set, access is
allowed from any 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. Providing a host name does not
guarantee security, because the actual value of the host name
can be overridden with the -H option 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 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. The path must be specified in
local file system syntax.

If you change this setting, you must physically relocate any
files that currently reside there. On Windows client machines,
you can specify the root as null to enable
you to map files to multiple drives.

AltRoots:

Writable, optional

Up to two optional alternate client workspace roots.

Perforce applications use the first of the main and alternate
roots that match the application's current working directory.
Use the p4
info command to display the root being used.

This enables users to use the same Perforce client workspace
specification on multiple platforms, even those with different
directory naming conventions.

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

If you are using a Windows directory in any of your workspace
roots, you must specify the Windows directory as your main
workspace root and specify your other workspace roots 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 workspace
options. See Usage Notes for a listing of
these options.

All open files (with or without changes) are submitted to
the depot. This is the default behavior of Perforce.

submitunchanged+reopen

All open files (with or without changes) are submitted to
the depot, and all files are automatically reopened in the
default changelist.

revertunchanged

Only those files with content, type, or resolved changes are
submitted to the depot. Unchanged files are reverted.

revertunchanged+reopen

Only those files with content, type, or resolved 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, type, or resolved changes are
submitted to the depot. Any unchanged files are moved to the
default changelist.

leaveunchanged+reopen

Only those files with content, type, or resolved 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

Configure carriage-return/linefeed (CR/LF) conversion. See
Usage Notes for a listing of these
options.

Stream:

Writable, optional

Associates the workspace with the specified stream. Perforce
generates the view for stream-associated workspaces: you cannot
modify it manually.

StreamAtChange:

Writable, optional

A changelist number that sets a back-in-time view of a stream.

When StreamAtChange is set, running
p4 sync (when
called with no arguments) updates the workspace to files at this
changelist revision, instead of the head revision. You cannot
submit changes (p4
submit returns an error) when
StreamAtChange is set, because the workspace
view no longer reflects the current stream inheritance.

This field is ignored unless the Stream field
is also set to a valid stream.

ServerID:

Writable, optional

If set, restricts usage of the workspace to the named server. If
unset, use is allowed on master server and on any replicas of
the master other than Edge servers.

View:

Writable, multi-line

Specifies the mappings between files in the depot and files in
the workspace. See p4 help views for more
information. A new view takes effect on the next p4
sync operation.

ChangeView:

Writable, optional, multi-line

Restricts access to depot paths to a particular point in time.
Files specified for the ChangeView field are read-only: they may
be opened but not submitted. For example:

//depot/path/...@1000

Revisions of the files in the specified path will not be visible
if they were submitted after the specified changelist number.
Files matching a ChangeView path may not be submitted.

Options

-d clientname

Delete the specified client workspace whether or not the
workspace is owned by the user. The workspace must be unlocked
and must have no opened files or pending changes. (The
-f option permits Perforce administrators
to delete locked workspaces owned by other users.) Clients can
be deleted even if they have shelved files (see
-Fs option).

-f

Allows the last modification date, which is normally read-only,
to be set. Administrators can use the -f option
to delete or modify locked workspaces owned by other users.

Allows the deletion of a client even when that client contains
shelved changes. The client is deleted and the shelved changes
are left intact. (You must use the -f option
with the -Fs option.)

-i

Read the client workspace specification from standard input.

-o

Write the client workspace specification to standard output.

-o -c change

When used with -S
stream, displays the
workspace specification that would have been created for a
stream at the moment the
change was submitted.

-s

Switch workspace view. To switch the workspace view to a stream,
specify -S stream.
To switch the view defined for another workspace, specify
-tclientname.

Switching views is not allowed in a client that has opened
files. The -f option can be used with
-s to force switching with opened files. View
switching has no effect on files in a client workspace until
p4 sync is run.

-S stream

Associates the workspace with the specified stream, which is
used to generate its workspace view.

-t clientname

Copy client workspace clientname's
view and options into the View: and
Options: field of this workspace. If you
specify a default client template using the
template.client configurable, you do not have
to specify this option.

Usage Notes

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

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

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

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

Use lowercase drive letters when specifying workspaces across multiple
drives.

Options field

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 in the workspace are left writable.

If allwrite is set and no
noclobber is specified, a safe
synchronization is performed.

A setting of allwrite leaves unopened files
writable by the current user; it does not set filesystem
permissions to ensure that files are writable by any user of a
multi-user system.

noallwrite

[no]clobber

If set, a p4
sync overwrites ("clobbers")
writable-but-unopened files in the workspace that have the
same name as the newly-synced files.

If allwrite is set and no
noclobber is specified, a safe
synchronization is performed.

noclobber

[no]compress

If set, the data stream between the user's workstation and the
Perforce service is compressed.

The compress option speeds up 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.

nocompress

[un]locked

Grant or deny other users permission to edit or delete the
workspace specification. (To make a locked
workspace truly effective, the workspace's owner's password
must be set with p4
passwd.)

If locked, only the owner is able to use or
edit the workspace specification. Perforce administrators can
override the lock by using the -f (force)
option with p4 client.

unlocked

[no]modtime

For files without the
+m (modtime) file type modifier:

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 version.

For files with the +m
(modtime) file type modifier: 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.

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
workspace's modtime or
nomodtime setting. For a more complete
discussion of the +m modifier, see
“File Types”.

nomodtime (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 workspace
if all files in the directory have been removed.

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
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 with your work.

normdir

Processing line endings

The LineEnd: field controls the line-ending
character(s) used for text files in the client workspace. Changing the
line end option does not actually update the client files; you can
refresh them with p4 sync -f.

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

Mac 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 already
synced into a workspace; however, when files are submitted to
the depot, 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 LF
line-endings untouched.

When you sync your workspace, line endings are set to
LF. If you edit the file on a Windows
machine, and your editor inserts CR
characters before each LF, the extra
CR characters 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 "CR/LF Issues and Text Line-endings" in the Perforce knowledge base:

Working with Streams

Without -s, the -S
stream option can be used to create
a new client spec dedicated to a stream. If the client spec already
exists, and -S is used without -s, it
is ignored. Using -S sets the client's
Stream field. The special syntax -S
//a/stream@changelist
can be used to set both Stream and
StreamAtChange at the same time.

The -S stream option can be
used with -o -c change to
inspect an old stream client view. It yields the client spec that would
have been created for the stream at the moment the change was recorded.

Working with build servers

A server of type build-server (see p4 help server) is
a replica that supports build farm integration, and the p4
client command may be used to create or edit client workspaces
on a build-server. Such workspaces may issue the
p4 sync command in
addition to any read-only command supported by the replica. For more
information, run p4 help buildserver.

When creating or editing a client workspace for a build-server, the
client specified by the optional name argument, as
well as the client specified by the P4CLIENT environment
variable or via the global -c client argument must not
exist, or must be restricted to this server; this command may not be
used to create or edit a workspace that is not restricted to this
build-server.

Examples

p4 client

Edit or create the workspace specification named by the value of
P4CLIENT or its
equivalents.

p4 client -t sue joe

Create or edit a workspace named joe, opening
the form with the field values and workspace options in the
workspace named sue as defaults.