Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Reference | 2025.1

# p4 client

Create or edit a client workspace specification and its view.

## Syntax

    p4 client [-f] [-t template] [-T type] [name]
    p4 client -d [-f [-Fs|-Fd]] name
    p4 client -o [-t template] [-T type] [name]
    p4 client -S stream [[-c change] -o] [name]
    p4 client -s [-f] -S stream [name]
    p4 client -s [-f] -t template [name]
    p4 client -i [-f]
    p4 client -d -f --serverid=X [-Fs] name

Syntax conventions

## Description

A P4 Server 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. Use the `p4 client` command to create or edit a client workspace specification. Invoking this command displays a form in which the user enters information so that the P4 Server can maintain the workspace.

The terms "client, "workspace", "client workspace", and "workspace client" mean the same thing.

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 and exiting the editor creates or modifies the client spec.

The client view, which is specified in the `p4 client` form’s `View` field, specifies the mapping between files in the workspace and depot.

The mapping between a client workspace file and a depot file:

- Can specify the same or different relative locations.
- Can specify the same or different names.
- Is typically a many-to-many mapping, such as `path/to/....html path/from/....htm`, where `...` is a wildcard and the fourth "." is the literal `.` before the file extension. See Wildcards in File specifications.

The new or altered client specification is stored in the P4 Server database (metadata Information that P4 Server maintains, such as who created file revisions in the depot, whether the file is a 'lazy copy,, the current state of client workspaces, protections, groups, users, labels, streams, and branches. Metadata is stored in the server database and is separate from the 'archive files' that users submit from their client workspace into the depot.). The files (versioned files Source files stored in the depot, including one or more revisions to each file. Also known as archive files, archives, and depot files. Versioned files typically use the naming convention 'filename,v' or '1.changelist.gz'.) in the workspace are not touched. The new view does not take effect until the next `p4 sync`.

To submit changes to a stream, you must associate the stream with a client workspace by 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`.

### About mapping in client workspace views

To exclude matching files, precede the mapping with the - minus sign.

If more than one mapping line refers to the same files, the later mapping line overrides the earlier one.

#### Map multiple server directories to the same client workspace directory

To map multiple server directories to the same client workspace directory, use the + sign to overlay the later mapping on an earlier one.

    //depot/project1/...     //bruno-client/project/...
    +//depot/project2/...    //bruno-client/project/...

If files match both the earlier and later mappings, the file matching the later mapping is used. To learn more, see Map different depot locations to the same workspace location in the P4 CLI Documentation.

#### Map a server directory to multiple client workspace directories

To map the same server directory to more than one client workspace directory, use the & sign.

    //depot/...     //bruno-client/...
    &//depot/and/tools/... //bruno-client/and/utility1/...
    &//depot/and/tools/... //bruno-client/and/utility2/...

Files mapped in this way are read-only. For more details, see Map a single depot path to multiple locations in a workspace in the P4 CLI Documentation.

## 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. Be aware of the Limitations on characters in filenames and entities.
`Owner:` | Writable, optional | The name of the workspace owner. The default owner is the user that created the workspace. The specified owner does not have to be a P4 Server 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. The access time is only valid for the server where the client resides, which is where the client was created or where the client was moved to. This is an issue only in a commit-edge architecture. 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. (See "Syntax forms" under File specifications) 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. P4 Server 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 P4 Server 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 switches that control particular workspace options. To learn more, see Options field.
`SubmitOptions:` | Writable, mandatory | Options to govern the default behavior of `p4 submit`. `submitunchanged` All open files (with or without changes) are submitted to the depot. This is the default behavior of P4 Server. `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 Processing line endings.
`Stream:` | Writable, optional | Associates the workspace with the specified stream. P4 Server generates the view for stream-associated workspaces. You cannot modify that view 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 the target server The immediately upstream server for replica servers, edge servers, standby servers, proxies and brokers. See also 'upstream server' and 'central server'. and on any replicas of the central server The one server that is innermost in a multi-server deployment. In the server specification form field for Services, the central server might be specified as “standard” or “commit-server”. If edge servers are part of the multi-server deployment, the central server must be a commit server. See also 'upstream server'. 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. Comments are preceded by `##` as shown in this example:
    View:
             ## Comment line
            //depot/main/...  "//eds_win/c:/Current Rel/..."  ## comment appended
`ChangeView:` | Writable, optional, multi-line | Restricts access to depot paths to a particular point in time. For example:
    //depot/path/...@1000
Revisions of the files in the specified path are not visible if they were submitted after the specified changelist number. Files matching a `ChangeView` path are read-only, and therefore cannot be: Opened for add, edit, delete, or integrate Shelved or submitted The names of automatic labels can be used as specifiers in import mappings on stream specs and in the `ChangeView` on client specs.
`Type:` | Writable, optional | Specifies the type of client workspace: `writeable`, `readonly`, `partitioned`, `partitioned-jnl`, or `graph`. By default, clients are created with the type `writeable`, and the `Type` field is not shown in the spec. The P4 Server uses a central `db.have` table to track the have list The list of file revisions most recently synced from the depot into the workspace. In other words, the list of files that the client workspace has. for `writeable` clients. However, when many clients syncing a large number of files at the same time, the central table is subject to contention. Other client types can reduce this contention because, for them, P4 Server uses client-specific `db.have.pt` tables that are independent of the central `db.have` table. To enable this feature, an administrator uses the `client.readonly.dir` configurable to set the location on the server for the independent `db.have` tables.
Type | Independent `db.have.pt` table? | Journaled, checkpointed, and recoverable? | Use Case
`writeable` | No | Yes | For general use.
`partitioned-jnl` | Yes | Yes | For general use in situations where client workspaces might otherwise experience contention for the server's central db.have table.
`readonly` | Yes | No | For short lived clients used in build automation scripts that do not edit or submit files.
`partitioned` | Yes | No | For short lived clients used in build automation scripts that do edit or submit files.
`graph` | No | Yes | For use with depots and repos of type graph and Git Connector. To learn more, see Work with Git.
### Replication Replication is supported for the client types that are journaled, checkpointed, and recoverable. Between Commit Servers and Edge Servers, only the client spec is replicated. To learn more, see Setting global client views in Client workspaces and client views. ## Converting client types The following tables indicates which client types can be converted to another client type.
| To writeable | To graph | To readonly | To partitioned | To partitioned-jnl
--- | --- | --- | --- | --- | ---
From writeable | Not applicable | If no open files and not a stream client | If no open files | Allowed | Allowed
From graph | If no open files | Not applicable | Not allowed | Not allowed | Not allowed
From readonly | Allowed | Not allowed | Not applicable | Allowed | Allowed
From partitioned | Allowed | Not allowed | If no open files | Not applicable | Allowed
From partitioned-jnl | Allowed | Not allowed | If no open files | Allowed | Not applicable
To learn more, see Client workspace types in the P4 Server Administration Documentation.

If there are one or more lines under a field, indent the lines. For example,

    Description:
        Created by maria

## Options

`-d name` | 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 combination of -d with -f allows the P4 Server administrator to delete a locked workspace that is owned by other user. This also reverts any files opened on the workspace. A user with `admin` or the owner can delete a workspace even if it has shelved files. See the -Fs and `-Fd` options. Otherwise, a client with shelved files cannot be deleted. If you try to forcibly delete a client bound to another server, you need to specify the `--serverid` option and specify the server id of the other server. This ensures that you do not accidentally delete the client believing it to be connected to your own server.
`-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. Use of this option requires `admin` access granted by `p4 protect`.
`-Fs` | Allows the deletion with `-d` 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.)
`-Fd` | Allows the deletion with `-d` of a client even when that client contains shelved changes. The client and the shelved changes are both deleted. (You must use the `-f` option with the `-Fd` 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 `-t clientname`. 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.
`--serverid=`X`` | If you try to forcibly delete a client bound to another server, you need to specify the `--serverid` option and specify the server id of the other server. This ensures that you do not accidentally delete the client believing it to be connected to your own server. This variant of the `p4 client` command must be issued directly to the commit server.
`-S stream` | Associates the workspace with the specified stream, which is used to generate its workspace view.
`-t name` | 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.
`-T type` | By default, clients are `writeable`. When you create a client workspace, use `-T type` to set a specific type. To learn more, see the Type: field.
`g-opts` | See Global options.

## Usage notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required | Command Alias
--- | --- | --- | ---
N/A | N/A | `list` `admin` for `-f` | `p4 workspace`

- 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 the `p4 client` `clientname` command. To prevent this, 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:

  Copy

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

  A comment in the View section has `##` at its beginning.

  Indent each line under a field, as shown above for Description: and View:

  Use lowercase drive letters when specifying workspaces across multiple drives.

### Options field

The `Options` field contains values separated by spaces. Each of the options has two possible settings:

Option | Choice | Default
--- | --- | ---
`[no]allwrite` | If `allwrite` is set, unopened files in the workspace are left writable. If `allwrite` is set and `noclobber` is NOT 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]altsync` | If `altsync` is set, and a P4 Virtual File Service (P4 VFS) application is installed to make use of P4ALTSYNC, the client can create, delete, or update placeholders of the file metadata instead of always taking time to download the full file content. See the P4 Virtual File Service (P4 VFS) Documentation. This option can only be changed when the client's have list is empty. See p4 have. | `noaltsync`
`[no]clobber` | If `clobber` is set, a `p4 sync` overwrites ("clobbers") files in the workspace that have the same name as the newly-synced files if those files are writable but unopened. If `allwrite` is set and `noclobber` is NOT specified, a safe synchronization is performed. | `noclobber`
`[no]compress` | If `compress` is set, the data stream between the user’s workstation and the P4 Server 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 might consume more time than is saved in transmission. | `nocompress`
`[un]locked` | Grant or deny other users permission to edit or delete the workspace specification. (To make a `locked` workspace 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. P4 Server 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 intended for 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 rmdir is set, when a command such as `p4 sync` causes a non-empty workspace directory to become empty, that workspace directory is deleted. If rmdir is set, `p4 sync` might remove your current working directory. If so, 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 update the client files until you refresh the client files 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 macOS) line endings: `LF`
`mac` | Mac pre-macOS: `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. The `share` option implicitly edits the files during a submit. As a consequence, if you have set the `LineEnd` field to `share` in your client spec, the `p4 resolve` command might prompt you to edit the file before resolving.

If all the servers run the same operating system, errors and confusion about file names can be avoided. To learn more, see Case sensitivity and multi-platform development in the P4 Server Administration Documentation.

### 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. The `p4 client` command can be used to create or edit client workspaces on a build-server. Such workspaces can 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 by the global `-c client` argument, must not exist, or must be restricted to this server. This command cannot be used to create or edit a workspace that is not restricted to this build-server.

### Working with read-only clients

Build automation scripts, which routinely create, sync, and tear down clients, can fragment the `db.have` table over time. To avoid this, you can specify the type `readonly` for these clients. Such clients cannot add, delete, edit, integrate, or submit files, but this should not be an issue in build scripts.

A readonly client is assigned its own personal `db.have` database table, and the location of this table is specified using the `client.readonly.dir` configurable.

To set up a read-only client:

1. Set the `client.readonly.dir` configurable to the directory where the db.* tables for the client should be stored.

   For example, if you create a read-only client whose name is `myroc` and you set `client.readonly.dir` to `/perforce/1`, then syncing files using this client will write to the following database

   `/perforce/1/server.dbs/client/`hashdir`/db.myroc`

2. Set the `Type` field of the client spec to `readonly`.

### Including Graph Depot repos in your client

See p4 client (graph).

## Examples

`p4 client` | Edit or create the workspace specification named by the value of `P4CLIENT` or its equivalents.
`p4 client -t gale bruno` | Create or edit a workspace named `bruno`, opening the form with the field values and workspace options in the workspace named `gale` as defaults.
`p4 client -d release1` | Delete the workspace named `release1`.
`p4 client -d -f -Fd release1` | As admin, delete both the workspace named `release1` and all of its shelved changes of another user.
p4 client -o build-client | sed "s/Created by/Created by automated build/" | p4 client -i | Automate the modification of the Description: field in a client specification. This example uses -o and -i to redirect from standard out to standard in.

## Related commands

To list all workspaces known to the system | `p4 clients`
To read files from the depot into the workspace | `p4 sync`
To open new files in the workspace for addition to the depot | `p4 add`
To open files in the workspace for edit | `p4 edit`
To open files in the workspace for deletion | `p4 delete`
To write changes in workspace files to the depot | `p4 submit`
Graph depot version | p4 client (graph)

Your search for returned results