Configure clients

You can configure many aspects of the behavior of a command-line client — such as which server port it listens on, the current client workspace name, and how files are mapped from the depot to the client workspace, among other things.

In Helix, the word "client" can refer to one of the following:

The client process — that is, the running client binary (p4)
The client workspace — the location on your computer where you work on file revisions managed by Helix

This chapter discusses configuring both.

Configure the client process

This guide refers to client settings using environment variables (for example, set P4CLIENT), but you can specify settings such as port, user, and workspace names using the following methods, listed in order of precedence:

On the command line, using options
In a config file, if P4CONFIG is set
User environment variables (on UNIX or Windows)
System environment variables (on Windows, system-wide environment variables are not necessarily the same thing as user environment variables)
On Windows or OS X, in the user registry or settings (set by issuing the p4 set command)
On Windows or OS X, in the system registry or system settings (set by issuing the p4 set -s command)

To configure your computer to connect to the Helix server, you specify the name of the host where the server is running, and the port on which it is listening. The default host is perforce and default port is 1666. If the server is running on your own computer, specify localhost as the host name. If the server is running on port 1666, you can omit the port specification.

You can specify these settings as described in the sections below. For details about working offline (without a connection to a Helix server), see Work offline.

Using the command line

To specify these settings on the command line, use the -p option. For example:

$ p4 -p tcp:localhost:1776 sync //JamCode/dev/jam/Jambase

Settings specified on the command line override any settings specified in config files, environment variables, the Windows registry, or OS X system settings. For more details about command-line options, refer to the discussion of global options in the P4 Command Reference.

Using config files

Config files are text files containing settings that are in effect for files in and below the directory where the config file resides. Config files are useful if you have multiple client workspaces on the same computer. By specifying the settings in config files, you avoid the inconvenience of changing system settings every time you want to work with a different workspace.

To use config files, you define the P4CONFIG environment variable, specifying a file name (for example, .p4config). When you issue a command, Helix searches the current working directory and its parent directories for the specified file and uses the settings it contains (unless the settings are overridden by command-line options).

Each setting in the file must be specified on its own line, using the following format:

setting=value

The following settings can be specified in a config file:

Setting	Description
`P4CHARSET`	Character set used for translation of Unicode files.
`P4COMMANDCHARSET`	Non-UTF-16 or UTF-32 character set used by Command-Line Client when `P4CHARSET` is set to a UTF-16 or UTF-32 character set.
`P4CLIENT`	Name of the current client workspace.
`P4DIFF`	The name and location of the diff program used by `p4 resolve` and `p4 diff`.
`P4EDITOR`	The editor invoked by those Helix commands that use forms.
`P4HOST`	Hostname of the client computer. Only useful if the `Host:` field of the current client workspace has been set in the `p4 client` form.
`P4IGNORE`	A list of files to ignore when using the `p4 add` and `p4 reconcile` commands.
`P4LANGUAGE`	This environment variable is reserved for system integrators.
`P4MERGE`	The name and location of the third-party merge program to be used by p4 resolve’s merge option.
`P4PASSWD`	Supplies the current Helix user’s password for any Helix command.
`P4PORT`	The protocol, host and port number of the Helix server (including proxies or brokers) with which to communicate.
`P4TRUST`	The location of a file of known (trusted) Helix servers. You manage the contents of this file with the `p4 trust` command. By default, this file is `.p4trust` in your home directory.
`P4USER`	Current Helix user name.

For details about these settings, refer to the P4 Command Reference.

Example 13. Using config files to handle switching between two workspaces.

Ona switches between two workspaces on the same computer. The first workspace is ona-ash. It has a client root of /tmp/user/ona and connects to the Helix server using SSL at ssl:ida:1818. The second workspace is called ona-agave. Its client root is /home/ona/p4-ona, and it uses a plaintext connection to a Helix server at tcp:warhol:1666.

Ona sets the P4CONFIG environment variable to .p4settings. She creates a file called .p4settings in /tmp/user/ona containing the following text:

P4PORT=ssl:ida:1818
P4CLIENT=ona-ash

She creates a second .p4settings file in /home/ona/p4-ona. It contains the following text:

P4PORT=tcp:warhol:1666
P4CLIENT=ona-agave

Any work she does on files under /tmp/user/ona is managed by the Helix server at ssl:ida:1818 and work she does on files under /home/ona/p4-ona is managed by the Helix server at tcp:warhol:1666.

Using environment variables

To configure connection settings using environment variables, set P4PORT to protocol:host:port, as in the following examples:

If the server runs on	and listens to port	supports encryption protocol	set `P4PORT` to
your computer	`1666`	nothing (plaintext)	`localhost:1666`
`perforce`	`1666`	SSL	`ssl:perforce:1666`
`houston`	`3435`	nothing (plaintext)	`tcp:houston:3435`
`example.com`	`1818`	SSL	`ssl:example.com:1818`

If you do not specify a protocol in your P4PORT setting, tcp: (plaintext communication over TCP/IP) is assumed. If the Helix server has been configured to support SSL, you can encrypt your connection to Helix by using ssl: as the desired protocol.

Other protocols (for example, tcp4: to require a plaintext IPv4 connection, or ssl64: to require an encrypted connection, but to prefer the use of the IPv6 transport instead of IPv4) are available for use in mixed networking environments.

See Configure for IPv6 networks, and the Helix Versioning Engine Administrator Guide: Fundamentals, for details.

Using the Windows registry or OS X system settings

On Windows and OS X computers, you can store connection settings in the registry (or system settings) by using the p4 set command. For example:

$ p4 set P4PORT=ssl:tea.example.com:1667

There are two ways you can configure client settings in the registry:

p4 set setting=value: for the current local user.
p4 set -s setting=value: for all users on the local computer. Can be overridden by any registry settings made for the local user. Requires administrative privileges.

To see which settings are in effect, use the p4 set command without arguments. For details about the p4 set command, see the P4 Command Reference.

Configure for IPv6 networks

Helix supports connectivity over IPv6 networks as well as over IPv4 networks.

Depending on the configuration of your LAN or WAN, your system administrator may recommend different port settings. Your administrator may also recommend that you set the net.rfc3484 configurable to 1, either from the command line or in a P4CONFIG file:

$ p4 configure set net.rfc3484=1

Doing so ensures RFC3484-compliant behavior if the protocol value is not explicitly specified; that is, if the client-side configurable net.rfc3484 is set to 1, and P4PORT is set to example.com:1666, or tcp:example.com:1666, or ssl:example.com:1666, the user’s operating system automatically determines, for any given connection, whether to use IPv4 or IPv6 when communicating with the versioning server.

Further information is available in the Helix Versioning Engine Administrator Guide: Fundamentals.

Configure for Unicode

The Helix server can be run in Unicode mode to activate support for file names or directory names that contain Unicode characters, and Helix identifiers (for example, user names) and specifications (for example, changelist descriptions or jobs) that contain Unicode characters.

In Unicode mode, the Helix server also translates Unicode files and metadata to the character set configured on the user’s computer, and verifies that the Unicode files and metadata contain valid UTF-8 characters.

Note

If you only need to manage textual files that contain Unicode characters, but do not need the features listed under Configure for Unicode, you do not need to run Helix in Unicode mode. Your system administrator will tell you if your site is using Unicode mode or not. For these installations, assign the Helix utf16 file type to textual files that contain Unicode characters. You do not have to set the P4CHARSET or P4COMMANDCHARSET environment variables. See Assigning file types for Unicode files for details.

To correctly inter-operate in Unicode mode, and to ensure that such files are translated correctly by the Helix server when the files are synced or submitted, you must set P4CHARSET to the character set that corresponds to the format used on your computer by the applications that access them, such as text editors or IDEs. These formats are typically listed when you save the file using the Save As… menu option.

Values of P4CHARSET that begin with utf16 or utf32 further require that you also set P4COMMANDCHARSET to a non utf16 or utf32 character set in which you want server output displayed. “Server output” includes informational and error messages, diff output, and information returned by reporting commands.

For a complete list of valid P4CHARSET values, issue the command p4 help charset.

For further information, see the Helix Versioning Engine Administrator Guide: Fundamentals.

Setting P4CHARSET on Windows

To set P4CHARSET for all users on a computer, you need Windows administrator privileges. Issue the following command:

C:\bruno_ws> p4 set -s P4CHARSET=character_set

To set P4CHARSET for the user currently logged in:

c:\bruno_ws> p4 set P4CHARSET=character_set

Your computer must have a compatible TrueType or OpenType font installed.

Setting P4CHARSET on UNIX

You can set P4CHARSET from a command shell or in a startup script such as .kshrc, .cshrc, or .profile. To determine the proper value for P4CHARSET, examine the setting of the LANG or LOCALE environment variable. Common settings are as follows

If `LANG` is…	Set `P4CHARSET` to
`en_US.ISO_8859-1`	`iso8859-1`
`ja_JP.EUC`	`eucjp`
`ja_JP.PCK`	`shiftjis`

In general, for a Japanese installation, set P4CHARSET to eucjp, and for a European installation, set P4CHARSET to iso8859-1.

Configure a client workspace

A Helix client workspace is a set of directories on your computer where you work on file revisions that are managed by Helix. Each workspace is given a name that identifies the client workspace to the Helix server. If no workspace name is specified (by setting the P4CLIENT environment variable) the default workspace name is the name of your computer. To specify the effective workspace name, set the P4CLIENT environment variable. You can have multiple workspaces on your computer.

All files within a Helix client workspace share a root directory, called the client workspace root. The workspace root is the highest-level directory of the workspace under which the managed source files reside.

If you configure multiple workspaces on the same computer, keep workspace locations separate to avoid inadvertently overwriting files. Ensure that client roots are located in different folders and that their workspace views do not map depot files to overlapping locations on your computer.

Although Windows-based systems do not have a root directory, Helix supports — via the concept of a null root — workspaces spread across multiple drives and/or a disjoint folder with only c:\ as the root.

How Helix manages files in a workspace

Helix manages the files in a client workspace as follows:

Files in the workspace are created, updated, and deleted as determined by your changes.
Write permission is enabled when you edit a file, and disabled when you submit your changes.

The state of your workspace is tracked and managed by Helix. To avoid conflicts with the file management performed by Helix applications, do not manually change read-only permission settings on files. Helix has commands that help you determine whether or not the state of your client workspace corresponds to Helix’s record of that state; see Work offline for details.

Files in the workspace that you have not put under Helix control are ignored by Helix. For example, compiled objects, libraries, executables, and developers’ temporary files that are created while developing software but not added to the depot are not affected by Helix commands.

By default, when you create a client workspace, the entire depot is mapped to your workspace. You can refine this mapping to view only a portion of the depot and to change the correspondence between depot and workspace locations, by refining the workspace view, as described in Configure workspace views.

Define a client workspace

To define a client workspace:

Specify the workspace name by setting P4CLIENT; for example, on a UNIX system:
```
$ export P4CLIENT=bruno_ws
```
Issue the p4 client command.

Important

Stream users must pass in the S _streamname option to the p4 client command to specify the name of the stream to which Helix should bind the workspace.

Helix displays the client specification form in your text editor. (For details about Helix forms, see Using Helix forms.)

Specify (at least the minimum) settings and save the specification.

No files are synced when you create a client specification. To find out how to sync files from the depot to your workspace, see Sync files. For details about relocating files on your computer, see Change the location and/or layout of your workspace.

The minimum settings you must specify to configure a client workspace are:

Workspace name

The workspace name defaults to your computer’s hostname, but your computer can contain multiple workspaces. To specify the effective workspace, set P4CLIENT.
Workspace root

The client workspace root is the top directory of your client workspace, where Helix stores your working copies of depot files. Be sure to set the workspace root, or you might inadvertently sync files to your computer’s root directory.

Note

For Windows users: when specifying a workspace root, you must include the drive letter. In addition, root is null on Windows when the client workspace is either on a disjoint drive with only c:\ as the root and/or is spread over multiple drives.

If the workspace root directory does not exist, you must create it before the Helix application can make use of it.

The @, #, *, and % characters have specific meaning to Helix; if you have file or folder names that use these characters, see Restrictions on filenames and identifiers for details.

Workspace view

By default, the entire depot is mapped to your workspace. You can define a workspace view (also referred to as a client view) to determine which files in the depot are mapped to your workspace; this enables Helix to construct a one-to-one mapping between individual depot and workspace files. You can map files to have different names and locations in your workspace than they have in the depot.

For users of streams, Helix generates the workspace view from the contents of the stream spec’s Paths: field. Users of classic Helix branches configure the workspace view by editing the contents of the client spec’s View: field.

For details on configuration of workspace views, see Configure workspace views.

Configure workspace options

The following table describes the client spec Options: in detail:

Option	Description	Default
`[no]allwrite`	Specifies whether unopened files are always writable. By default, Helix makes unopened files read-only. To avoid inadvertently overwriting changes or causing syncs to fail, specify `noallwrite`. 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 multiuser system. If `allwrite` and `noclobber` are both set, Helix performs a safe sync, comparing the content in your client workspace against what was last synced. If the file was modified outside of Helix control, an error message is displayed and the file is not overwritten.	`noallwrite`
`[no]clobber`	Specifies whether `p4 sync` overwrites writable but unopened workspace files. (By default, Helix does not overwrite unopened files if they are writable.) If `allwrite` and `noclobber` are both set, Helix performs a safe sync, comparing the content in your client workspace against what was last synced. If the file was modified outside of Helix control, an error message is displayed and the file is not overwritten.	`noclobber`
`[no]compress`	Specifies whether data is compressed when it is sent between your computer and the Helix server.	`nocompress`
`[un]locked`	Specifies whether other users can use, edit, or delete the client workspace specification. A Helix administrator can override the lock with the `-f` (force) option. If you lock your client specification, be sure to set a password for the workspace’s owner using the `p4 passwd` command.	`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 submitted to the depot. If `nomodtime` is set, the modification date is the date and time of sync. For files with the `+m` (modtime) file type, 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` (date and time of sync). Ignored for files with the `+m` file type modifier.
`[no]rmdir`	Specifies whether `p4 sync` deletes empty directories in a workspace if all files in the directory have been removed.	`normdir`

Configure submit options

To control what happens to files in a changelist when you submit the changelist to the depot, set the SubmitOptions: field. Valid settings are as follows.

Option	Description
`submitunchanged`	All open files (with or without changes) are submitted to the depot. This is the default behavior of Helix.
`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.

View a stream as of a specific changelist

The StreamAtChange option in the client spec lets you use the version of the stream specified as of a particular changelist to generate a workspace view. This is helpful when you want to see what the stream view was at a particular point in time, especially if your stream spec changes a lot (for example, if you frequently change what you’re importing or what you’re deciding to share). When you use the StreamAtChange option, you cannot submit changes to the files in the stream, since your workspace view is not up to date.

To set a stream workspace to use the version of the stream specified as of a particular changelist, do the following:

Open the stream’s workspace specification form for editing.
```
$ p4 client
```
Use one of the following alternatives:
1. Edit the form to set StreamAtChange: to the changelist you want to view the stream as of. Or,
2. Issue this command:
```
$ p4 client -S //Ace/main@12546
```

For more information, see the P4 Command Reference.

Alternatively, you can issue the following command to sync a stream using the stream’s view as of a specific changelist:

$ p4 switch [-r -v] stream@change

This command both sets the StreamAtChange value and syncs to the same change.

Configure line-ending settings

To specify how line endings are handled when you sync text files, set the LineEnd: field. Valid settings are as follows:

Option	Description
`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 that are synced into a client workspace; however, when files are submitted back to the Helix 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 `LF`s untouched. When you sync your client workspace, line endings are set to `LF`. If you edit the file on a Windows computer, and your editor inserts `CR`’s before each `LF`, the extra `CR`’s do not appear in the archive file. The most common use of the `share` option is for users of Windows computers who mount their UNIX home directories as network drives; if you sync files from UNIX, but edit the files on a Windows computer. The `share` option implicitly edits the file(s) during a submit. As a consequence, if you have set the `LineEnd` field to `share` in your client spec, the `p4 resolve` command may prompt you to edit the file before resolving.

For detailed information about how Helix uses the line-ending settings, see “CR/LF Issues and Text Line-endings” in the Helix knowledge base:

http://answers.perforce.com/articles/KB_Article/CR-LF-Issues-and-Text-Line-endings

Change the location and/or layout of your workspace

To change the location of files in your workspace, issue the p4 client command and change either or both of the Root: and View: fields. Before changing these settings, ensure that you have no files checked out (by submitting or reverting open files).

If you’re using streams, you must change the Paths: field in the stream spec, rather than the View: field, in the client spec.

If you intend to modify both fields, perform the following steps to ensure that your workspace files are located correctly:

To remove the files from their old location in the workspace, issue the p4 sync …#none command.
Change the Root: field. (The new client workspace root directory must exist on your computer before you can retrieve files into it.)
To copy the files to their new locations in the workspace, perform a p4 sync. (If you forget to perform the p4 sync …#none before you change the workspace view, you can always remove the files from their client workspace locations manually).
Users of streams, change the Paths: field in the stream spec. Users of classic Helix branches, change the View: field in the client spec.
Again, perform a p4 sync. This time, syncing changes the layout of the workspace. The files in the client workspace are synced to their new locations.

Manage workspaces

This section discusses various approaches to managing your stream workspaces.

Using one workspace for multiple streams

When working with multiple streams, you have two choices:

Switch one workspace between multiple streams; the workspace is appropriately populated whenever you switch from one stream to another. While this requires some extra processing, it is the right choice when you don’t need to work on different streams at the same time and you don’t want to have multiple streams on disk at the same time.
Establish a distinct workspace for each stream. This is the right choice if you want to move quickly between different streams or if you want to have multiple streams on disk at the same time.

Note that distinct workspaces must have distinct workspace roots — that is, distinct local folders.

To change the stream associated with a workspace, issue the following command:

$ p4 switch streamname

To get a workspace view and a set of files as of a specific changelist, issue the following command:

$ p4 switch stream@change

Narrowing the scope of workspaces with virtual streams

For large projects, even consistently-organized streams may not sufficiently restrict workspace views. In large organizations, there are often many groups who are concerned with only a small subset of a project’s files. In classic Helix, these users would manually restrict their workspace’s view to include only the desired subset. Streams offer an analog; use a virtual stream as a filter:

For example, if ongoing development work is occurring in an //Ace/dev stream:

Stream:     //Ace/dev
Parent:     //Ace/main
Type:       development
Paths:
        share ...

Then a user who is working only with the documentation for the product (rather than all of the assets associated with the project) could create a virtual stream that includes only those files under //Ace/dev/docs/..., as follows:

Stream:     //Ace/devdocs
Parent:     //Ace/dev
Type:       virtual
Paths:
        share docs/...

The user can then can switch his or her workspace to the devdocs virtual stream with the following command:

$ p4 switch //Ace/devdocs

When using the devdocs workspace, the user’s workspace view is automatically updated to include only the material in //Ace/dev/docs/... and any changes he or she makes in //Ace/devdocs are automatically made directly in the original //Ace/dev codeline without the need to manually run p4 copy or p4 merge.

For details on virtual streams, see Virtual streams.

Delete a client workspace

To delete a workspace, issue the p4 client -d clientname command. Deleting a client workspace removes Helix’s record of the workspace but does not remove files from the workspace or the depot.

When you delete a workspace specification:

Revert (or submit) any pending or shelved changelists associated with the workspace.
Delete existing files from a client workspace (p4 sync ...#none). (optional)
Delete the client spec.

If you delete the client spec before you delete files in the workspace, you can delete workspace files using your operating system’s file deletion command.

Configure workspace views

Helix generates workspace views automatically, from the stream spec, for all workspaces bound to that stream. When you bind a workspace to a stream, Helix generates the workspace view based on the structure of the stream. Specifically, it bases it on the depot mapping entries in the stream spec’s Paths: field. If the structure of the stream changes, Helix updates the views of workspaces associated with the stream on an as-needed basis.

For details on all stream spec fields, see Configure a stream.

Note

Classic users update the workspace view manually, by editing the View: field in the client spec (invoked with the p4 client command.)

To modify a workspace view, issue the p4 stream command. Helix displays the stream specification form, which lists mappings in the Paths: field.

Suppose your stream spec contains the following entries under Paths::

Paths:
import ...
isolate apps/bin/...
share apps/xp/...
exclude tests/...

Switching your workspace to this stream gives you this workspace view:

//Acme/XProd/apps/bin/... //bruno_ws/apps/bin/... 
//Acme/XProd/apps/xp/...  //bruno_ws/apps/xp/... 
-//Acme/XProd/tests/...   //bruno_ws/tests/...

The sections below provide details about specifying the workspace view. For more information, see the description of views in the P4 Command Reference.

Specify mappings

Views consist of multiple mappings. Each mapping has two parts.

The left-hand side specifies one or more files in the depot and has the form: //depotname/file_specification
The right-hand side specifies one or more files in the client workspace and has the form: //clientname/file_specification

The left-hand side of a workspace view mapping is called the depot side, and the right-hand side is the client side.

To determine the location of any workspace file on your computer, substitute the client workspace root for the workspace name on the client side of the mapping. For example, if the workspace root is C:\bruno_ws, the file //JamCode/dev/jam/Jamfile resides in C:\bruno_ws\dev\jam\Jamfile.

Later mappings override earlier ones. In the example below, the second line overrides the first line, mapping the files in //Acme/dev/docs/manuals/ up two levels. When files in //Acme/dev/docs/manuals/ are synced, they reside in c:\bruno_ws\docs\.

View:
    //Acme/dev/...            //bruno_ws/dev/...
    //Acme/dev/docs/...       //bruno_ws/docs/...

Use wildcards in workspace views

To map groups of files in workspace views, you use Helix wildcards. Any wildcard used on the depot side of a mapping must be matched with an identical wildcard in the mapping’s client side. You can use the following wildcards to specify mappings in your client workspace:

Wildcard	Description
`*`	Matches anything except slashes. Matches only within a single directory. Case sensitivity depends on your platform.
`...`	Matches anything including slashes. Matches recursively (everything in and below the specified directory).
`%%1 - %%9`	Positional specifiers for substring rearrangement in filenames.

In the following simple workspace view, all files in the depot’s dev stream are mapped to the corresponding locations in the client workspace:

//JamCode/dev/... //bruno_ws/dev/...

For example, the file //JamCode/dev/jam/Makefile is mapped to the workspace file C:\bruno_ws\dev\jam\Makefile.

Note

To avoid mapping unwanted files, always precede the ... wildcard with a forward slash.

The mappings in workspace views always refer to the locations of files and directories in the depot; you cannot refer to specific revisions of a file in a workspace view.

Map part of the depot

If you are interested only in a subset of the depot files, map that portion. Reducing the scope of the workspace view also ensures that your commands do not inadvertently affect the entire depot. To restrict the workspace view, change the left-hand side of the View: field to specify the relevant portion of the depot.

Example 14. Mapping part of the depot to the client workspace.

Dai is working on the Jam project and maintaining the web site, so she sets the View: field as follows:

View:
    //JamCode/dev/jam/...       //dai-beos-locust/jam/...
    //JamCode/www/live/...      //dai-beos-locust/www/live/...

Map files to different locations in the workspace

Views can consist of multiple mappings, which are used to map portions of the depot file tree to different parts of the workspace file tree. If there is a conflict in the mappings, later mappings have precedence over the earlier ones.

Example 15. Multiple mappings in a single workspace view.

The following view ensures that Microsoft Word files in the manuals folder reside in the workspace in a top-level folder called wordfiles:

View:
    //depot/...                          //bruno_ws/...
    //Acme/dev/docs/manuals/*.doc        //bruno_ws/wordfiles/*.doc

Map files to different filenames

Mappings can be used to make the filenames in the workspace differ from those in the depot.

Example 16. Files with different names in the depot and the workspace

The following view maps the depot file RELNOTES to the workspace file rnotes.txt:

View:
    //depot/...                   //bruno_ws/...
    //JamCode/dev/jam/RELNOTES //bruno_ws/dev/jam/rnotes.txt

Rearrange parts of filenames

Positional specifiers %%0 through %%9 can be used to rearrange portions of filenames and directories.

Example 17. Using positional specifiers to rearrange filenames and directories.

The following view maps the depot file //depot/allfiles/readme.txt to the workspace file filesbytype/txt/readme:

View:
    //depot/allfiles/%%1.%%2  //bruno_ws/filesbytype/%%2/%%1

Exclude files and directories

Exclusionary mappings enable you to explicitly exclude files and directories from a workspace. To exclude a file or directory, precede the mapping with a minus sign (-). White space is not allowed between the minus sign and the mapping.

Example 18. Using views to exclude files from a client workspace.

Earl, who is working on the Jam project, does not want any HTML files synced to his workspace. His workspace view looks like this:

View:
    //JamCode/dev/jam/...        //earl-dev-beech/jam/...
    -//JamCode/dev/jam/....html  //earl-dev-beech/jam/....html

Map a single depot path to multiple locations in a workspace

Helix includes a "one-to-many" mapping feature, with which you can map a single depot path to multiple locations in a client workspace.

Important

This feature is currently only available for users of classic Helix branches; one-to-many mapping is not available for streams.

Consider the following scenario: A company has a website whose content is divided into categories such as products, documentation, and technical support. The content for each of these categories is managed in its own location in the workspace.

However, all of these websites display the same logo. Consequently, all three of the locations in the workspace must contain the same image file for the logo.

You might try to map the depot path like this:

View:
    //Acme/images/logo.png  //bruno_ws/products/images/logo.png
    //Acme/images/logo.png  //bruno_ws/documentation/images/logo.png
    //Acme/images/logo.png  //bruno_ws/support/images/logo.png

When you sync the client, the depot file will only be mapped to the support location in the workspace. By default, in a situation in which a workspace view maps a depot path to multiple locations in a client, only the last location in the list is the one to which the depot files are actually mapped.

To enable Helix’s one-to-many mapping feature, prepend & to the mapping line for each additional client location you want to map to, as in the following example:

View:
    //Acme/images/logo.png  //bruno_ws/products/images/logo.png
   &//Acme/images/logo.png  //bruno_ws/documentation/images/logo.png
   &//Acme/images/logo.png  //bruno_ws/support/images/logo.png

This time when you sync the client, the depot file will be mapped to all three locations. However, note that bruno_ws/documentation, and bruno_ws/support are read only-because all mapping line prepended with & are read-only.

Restrict access by changelist

You can restrict access to depot paths to a particular point in time by providing the depot path names and changelist numbers in the ChangeView field of the client specification. Files specified for the ChangeView field are read-only: they can be opened but not submitted. For example:

ChangeView:
      //depot/path/...@1000

In this example, revisions of the files in //depot/path/... are not visible if they were submitted after changelist 1000. Files submitted up to and including changelist 1000 are visible but read-only. You can specify multiple paths.

You may specify ChangeView entries in either depot syntax or client syntax.

Avoid mapping conflicts

When you use multiple mappings in a single view, a single file can inadvertently be mapped to two different places in the depot or workspace. When two mappings conflict in this way, the later mapping overrides the earlier mapping.

Example 19. Erroneous mappings that conflict.

Joe has constructed a view as follows:

View:
    //Acme/proj1/...    //joe/project/...
    //Acme/proj2/...    //joe/project/...

The second mapping //Acme/proj2/... maps to //joe/project and conflicts with the first mapping. Because these mappings conflict, the first mapping is ignored; no files in //Acme/proj1 are mapped into the workspace: //Acme/proj1/file.c is not mapped, even if //Acme/proj2/file.c does not exist.

Automatically prune empty directories from a workspace

By default, Helix does not remove empty directories from your workspace. To change this behavior, issue the p4 client command and in the Options: field, change the option normdir to rmdir.

For more about changing workspace options, see Configure workspace options.

Map different depot locations to the same workspace location

Overlay mappings enable you to map files from more than one depot directory to the same place in a workspace. To overlay the contents of a second directory in your workspace, use a plus sign (+) in front of the mapping.

Example 20. Overlaying multiple directories in the same workspace.

Joe wants to combine the files from his projects when they are synced to his workspace, so he has constructed a view as follows:

View:
    //Acme/proj1/...    //joe/project/...
    +//Acme/proj2/...   //joe/project/...

The overlay mapping //Acme/proj2/... maps to //joe/project, and overlays the first mapping. Overlay mappings do not conflict. Files (even deleted files) in //Acme/proj2 take precedence over files in //Acme/proj1. If //Acme/proj2/file.c is missing (as opposed to being present, but deleted), then //Acme/proj1/file.c is mapped into the workspace instead.

Overlay mappings are useful for applying sparse patches in build environments.

Deal with spaces in filenames and directories

Use quotation marks to enclose files or directories that contain spaces.

Example 21. Dealing with spaces in filenames and directories.

Joe wants to map files in the depot into his workspace, but some of the paths contain spaces:

View:
    "//Acme/Release 2.0/..."   //joe/current/...
    "//Acme/Release 1.1/..."   "//joe/Patch Release/..."
    //Acme/webstats/2011/...   "//joe/2011 Web Stats/..."

By placing quotation marks around the path components on the server side, client side, or both sides of the mappings, Joe can specify file names and/or directory components that contain spaces.

For more information, see Spaces in filenames, pathnames, and identifiers.

Map Windows workspaces across multiple drives

To specify a workspace that spans multiple Windows drives, use a Root: of null and specify the drive letters (in lowercase) in the workspace view. For example:

Client:     bruno_ws
Update:     2011/11/29 09:46:53
Access:     2011/03/02 10:28:40
Owner:      bruno
Root:       null
Options:    noallwrite noclobber nocompress unlocked nomodtime normdir
SubmitOptions: submitunchanged
LineEnd:    local
View:
    //Acme/dev/...      "//bruno_ws/c:/Current Release/..."
    //Acme/release/...  "//bruno_ws/d:/Prior Releases/..."
    //Acme/www/...      //bruno_ws/d:/website/...

Use the same workspace from different computers

By default, you can only use a workspace on the computer that is specified by the Host: field. If you want to use the same workspace on multiple computers with different platforms, delete the Host: entry and set the AltRoots: field in the client specification. You can specify a maximum of two alternate workspace roots. The locations must be visible from all computers that will be using them, for example through NFS or Samba mounts.

Helix compares the current working directory against the main Root: first, and then against the two AltRoots: if specified. The first root to match the current working directory is used. If no roots match, the main root is used.

Note

If you are using a Windows directory in any of your workspace roots, specify the Windows directory as your main client Root: and specify your other workspace root directories in the AltRoots: field.

In the example below, if user bruno’s current working directory is located under /usr/bruno, Helix uses the UNIX path as his workspace root, rather than c:\bruno_ws. This approach allows bruno to use the same client specification for both UNIX and Windows development.

Client: bruno_ws
Owner:  bruno
Description:
        Created by bruno.
Root:   c:\bruno_ws
AltRoots:
        /usr/bruno/

To find out which client workspace root is in effect, issue the p4 info command and check the Client root: field.

If you edit text files in the same workspace from different platforms, ensure that the editors and settings you use preserve the line endings. For details about line-endings in cross-platform settings, see Configure line-ending settings.

Helix Versioning Engine User Guide (2016.2)

Configure clients

Configure the client process

Using the command line

Using config files

Using environment variables

Using the Windows registry or OS X system settings

Configure for IPv6 networks

Configure for Unicode

Note

Setting P4CHARSET on Windows

Setting P4CHARSET on UNIX

Configure a client workspace

How Helix manages files in a workspace

Define a client workspace

Important

Note

Configure workspace options

Configure submit options

View a stream as of a specific changelist

Configure line-ending settings

Change the location and/or layout of your workspace

Manage workspaces

Delete a client workspace

Configure workspace views

Note

Specify mappings

Use wildcards in workspace views

Note

Map part of the depot

Map files to different locations in the workspace

Map files to different filenames

Rearrange parts of filenames

Exclude files and directories

Map a single depot path to multiple locations in a workspace

Important

Restrict access by changelist

Avoid mapping conflicts

Automatically prune empty directories from a workspace

Map different depot locations to the same workspace location

Deal with spaces in filenames and directories

Map Windows workspaces across multiple drives

Use the same workspace from different computers

Note