Configuring P4
This chapter tells you how to configure connection settings.
Configuration overview
Perforce is an enterprise version management system in which you connect to a shared versioning service; users sync files from the shared repository, called the depot, and edit them on your workstation in your client workspace. This chapter assumes that your system administrator has configured your organization's Perforce service. For details about setting up the versioning service, refer to the Perforce Server Administrator's Guide: Fundamentals.
To set up your workspace so you can work with Perforce, perform the following steps:
-
Configure settings for the protocol, host, and port (so you can connect to the Perforce service). See Configuring Perforce settings.
-
Define your workspace (at a minimum, assign a name and specify a workspace root where you want local copies of depot files stored). See Defining client workspaces.
-
Verify the connection. See Verifying connections.
After you configure your workspace, you can populate it by syncing files that are stored in the depot. For details, see Syncing (retrieving) files and the description of the p4 sync command in the P4 Command Reference.
Before you start to configure Perforce, ask your Perforce administrator for the proper host and port setting. Also ask whether a workspace has already been configured for your workstation.
What is a client workspace?
A Perforce client workspace is a set of directories on your
workstation where you work on file revisions that are managed by Perforce. Each workspace is
given a name that identifies the client workspace to the Perforce service. If no workspace
name is specified (by setting the P4CLIENT
environment variable) the default
workspace name is the name of your workstation. To specify the effective workspace name, set
the P4CLIENT
environment variable. You can have multiple workspaces on your
machine.
All files within a Perforce 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 machine, 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 workstation.
After you configure your workspace, you can sync files from the depot and submit changes. For details about these tasks, refer to “Managing Files and Changelists”.
How Perforce manages the workspace
Perforce 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 Perforce. To avoid conflicts with the file management performed by Perforce applications, do not manually change read-only permission settings on files. Perforce has commands that help you determine whether or not the state of your client workspace corresponds to Perforce's record of that state; see Working offline for details.
Files in the workspace that you have not put under Perforce control are ignored by Perforce. 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 Perforce commands.
After defining your client workspace, you can fine-tune the workspace definition. Probably most important, you can restrict the portion of the depot that is visible to you, to prevent you from inadvertently syncing the entire depot. For details, refer to Refining workspace views.
Configuring Perforce settings
This guide refers to Perforce settings using environment variables (for example, set P4CLIENT), but you can specify Perforce settings such as port, user, and workspace names using the following methods, listed in order of precedence:
-
On the command line, using flags
-
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 workstation to connect to the Perforce service, you specify the name of
the host where the service is running, and the port on which it is listening. The default host
is perforce
and default port is 1666. If the service is running on your own
machine, specify localhost
as the host name. If the service is running on
port 1666, you can omit the port specification.
You can specify these settings as described in the following sections. For details about working offline (without a connection to a Perforce service), see Working offline.
Using the command line
To specify these settings on the command line, use the -p
flag.
For example:
p4 -p tcp:localhost:1776 sync //depot/dev/main/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 flags, refer to the discussion of global options in the P4 Command Reference.
Using config files
Config files are text files containing Perforce 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 machine. 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, Perforce 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 flags).
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 |
---|---|
|
Character set used for translation of Unicode files. |
|
Non-UTF-16 or UTF-32 character set used by Command-Line Client when
|
|
Name of the current client workspace. |
|
The name and location of the diff program used by p4 resolve and p4 diff. |
|
The editor invoked by those Perforce commands that use forms. |
|
Hostname of the client workstation. Only useful if the
|
|
A list of files to ignore when using the p4 add and p4 reconcile commands. |
|
This environment variable is reserved for system integrators. |
|
The name and location of the third-party merge program to be used by p4 resolve's merge option. |
|
Supplies the current Perforce user's password for any Perforce command. |
|
The protocol, host and port number of the Perforce service (including proxies or brokers) with which to communicate. |
|
The location of a file of known (trusted) Perforce servers. You manage the
contents of this file with the p4 trust command. By default,
this file is |
|
Current Perforce user name. |
For details about these settings, refer to the P4 Command Reference.
Example 1. Using config files to handle switching between two workspaces
Ona switches between two workspaces on the same machine. The first workspace is
ona-ash
. It has a client root of /tmp/user/ona
and connects to the Perforce service 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 Perforce
service 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:1818P4CLIENT=ona-ash
She creates a second .p4settings
file in
/home/ona/p4-ona
. It contains the following text:
P4PORT=tcp:warhol:1666P4CLIENT=ona-agave
Any work she does on files under /tmp/user/ona
is managed by the
Perforce service at ssl:ida:1818
and work she does on files under
/home/ona/p4-ona
is managed by the Perforce service 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 service runs on |
and listens to port |
supports encryption protocol |
set P4PORT to |
---|---|---|---|
your computer |
|
nothing (plaintext) |
|
|
|
SSL |
|
|
|
nothing (plaintext) |
|
|
|
SSL |
|
If you do not specify a protocol in your P4PORT
setting,
tcp:
(plaintext communication over TCP/IP) is assumed. If the Perforce
service has been configured to support SSL, you can encrypt your connection to Perforce 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 Connecting over IPv6 networks, and the Perforce Server Administrator's Guide: Fundamentals, for details.
Using the Windows registry or OS X system settings
On Windows and OS X machines, 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 Perforce settings in the registry:
-
p4 set
setting=value
: for the current local user. -
p4 set -s
setting=value
: for all users on the local machine. 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.
Defining client workspaces
To define a client workspace:
-
Specify the workspace name by setting
P4CLIENT
; for example, on a UNIX system:$ P4CLIENT=bruno_ws ; export P4CLIENT
-
Issue the p4 client command.
Perforce displays the client workspace specification form in your text editor. (For details about Perforce forms, refer to Using Perforce 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, refer to Syncing (retrieving) files. For details about relocating files on your machine, see Changing the location of your workspace.
The minimum settings you must specify to configure a client workspace are:
-
Workspace name
The workspace name defaults to your machine's hostname, but a your workstation 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 Perforce stores your working copies of depot files. Be sure to set the workspace root, or you might inadvertently sync files to your workstation's root directory. (When specifying a workspace root on Windows, you must also include the drive letter.)
If the workspace root directory does not exist, you must create it before the Perforce application can make use of it.
The
@
,#
,*
, and%
characters have specific meaning to Perforce; if you have file or folder names that use these characters, see Restrictions on filenames and identifiers for details.
Your client workspace view determines which files in the depot are mapped to your workspace and enables Perforce 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, but you cannot map files to multiple locations in the workspace or the depot. By default, the entire depot is mapped to your workspace. You can define a client workspace view to map only files and directories of interest, so that you do not inadvertently sync the entire depot into your workspace. For details, see Refining workspace views.
Example 2. Setting the workspace view
Bruno issues the p4 client command and sees a form containing this default client workspace view definition:
Client: bruno_ws Update: 2014/05/12 09:46:53 Access: 2014/05/12 10:28:40 Owner: bruno Host: dhcp_24-n102.dhcp.perforce.com Description: Created by jbruges. Root: c:\bruno_ws Options: :noallwrite noclobber nocompress unlocked nomodtime normdir SubmitOptions: submitunchanged LineEnd: local View: //depot/... //bruno_ws/...
He modifies the view to map only the development portion of the depot.
View: //depot/dev/... //bruno_ws/dev/...
He further modifies the view to map files from multiple depots into his workspace.
View: //depot/dev/... //bruno_ws/depot/dev/... //testing/... //bruno_ws/testing/... //archive/... //bruno_ws/archive/...
Verifying connections
To verify a connection, issue the p4 info command. If
P4PORT
is set correctly, information like the following is displayed:
User name: bruno Client name: bruno_ws Client host: workstation_12 Client root: c:\bruno_ws Current directory: c:\bruno_ws Peer address; 10.0.102.24:61122 Client address: 10.0.0.196 Server address: ssl:example.com:1818 Server root: /usr/depot/p4d Server date: 2012/03/28 15:03:05 -0700 PDT Server uptime: 752:41:33 Server version: P4D/FREEBSD/2012.1/406375 (2012/01/25) ServerID: Master Server license: P4Admin <p4adm> 20 users (expires 2015/01/01) Server license-ip: 10.0.0.2 Case handling: sensitive
The Server address:
field shows the host to which
p4 connected and also displays the host and port number on which the
Perforce service is listening. If P4PORT
is set incorrectly, you receive a
message like the following:
Perforce client error: Connect to server failed; check $P4PORT. TCP connect to perforce:1666 failed. perforce: host unknown.
If the value you see in the third line of the error message is
perforce:1666
(as above), P4PORT
has not been set. Set
P4PORT
and try to connect again.
If your installation requires SSL, make sure your P4PORT
is of the form
ssl:
hostname
:
port
.
You will be asked to verify the server's fingerprint the first time you attempt to
connect to the service. If the fingerprint is accurate, use the p4 trust
command to install the fingerprint into a file (pointed to by the P4TRUST
environment variable) that holds a list of known/trusted Perforce servers and their respective
fingerprints. If P4TRUST
is unset, this file is .p4trust
in the user's home directory. For more information, see SSL-encrypted connections.
If your installation requires plaintext (in order to support older Perforce
applications), set P4PORT
to
tcp:
hostname
:
port
.
Connecting over IPv6 networks
As of Release 2013.1, Perforce 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 service.
Further information is available in the Perforce Server Administrator's Guide: Fundamentals.
Refining workspace views
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.
To display or modify a workspace view, issue the p4 client command.
Perforce displays the client workspace specification form, which lists mappings in the
View:
field:
Client: bruno_ws Owner: bruno Description: Created by bruno. Root: C:\bruno_ws Options: noallwrite noclobber nocompress unlocked nomodtime normdir SubmitOptions: submitunchanged View: //depot/... //bruno_ws/...
The following sections provide details about specifying the client workspace view. For more information, see the p4 client command description and the description of views in the P4 Command Reference.
Specifying 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 client 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 workstation, 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
//depot/dev/main/jam/Jamfile
resides in
C:\bruno_ws\dev\main\jam\Jamfile
.
Later mappings override earlier ones. In the following example, the second line
overrides the first line, mapping the files in
//depot/dev/main/docs/manuals/
up two levels. When files in
//depot/dev/main/docs/manuals/
are synced, they reside in
c:\bruno_ws\docs\
.
View: //depot/dev/... //bruno_ws/dev/... //depot/dev/main/docs/... //bruno_ws/docs/...
Using wildcards in workspace views
To map groups of files in workspace views, you use Perforce 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). |
|
Positional specifiers for substring rearrangement in filenames. |
In this simple client workspace view:
//depot/dev/... //bruno_ws/dev/...
all files in the depot's dev
branch are mapped to the corresponding
locations in the client workspace. For example, the file
//depot/dev/main/jam/Makefile
is mapped to the workspace file
C:\bruno_ws\dev\main\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.
Mapping 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 3. 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: //depot/dev/main/jam/... //dai-beos-locust/jam/... //depot/www/live/... //dai-beos-locust/www/live/...
Mapping 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 4. 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/... //depot/dev/main/docs/manuals/*.doc //bruno_ws/wordfiles/*.doc
Mapping files to different filenames
Mappings can be used to make the filenames in the workspace differ from those in the depot.
Example 5. 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/... //depot/dev/main/jam/RELNOTES //bruno_ws/dev/main/jam/rnotes.txt
Rearranging parts of filenames
Positional specifiers %%0
through %%9
can be used
to rearrange portions of filenames and directories.
Example 6. 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
Excluding 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 7. 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: //depot/dev/main/jam/... //earl-dev-beech/jam/... -//depot/dev/main/jam/....html //earl-dev-beech/jam/....html
Restricting 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 workspace 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.
Avoiding 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 8. Erroneous mappings that conflict
Joe has constructed a view as follows:
View: //depot/proj1/... //joe/project/... //depot/proj2/... //joe/project/...
The second mapping //depot/proj2/...
maps to
//joe/project
and conflicts with the first mapping. Because these
mappings conflict, the first mapping is ignored; no files in
//depot/proj1
are mapped into the workspace:
//depot/proj1/file.c
is not mapped, even if
//depot/proj2/file.c
does not exist.
Mapping 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 9. 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: //depot/proj1/... //joe/project/... +//depot/proj2/... //joe/project/...
The overlay mapping +//depot/proj2/...
maps to
//joe/project
, and overlays the first mapping. Overlay mappings do
not conflict. Files (even deleted files) in //depot/proj2
take
precedence over files in //depot/proj1
. If
//depot/proj2/file.c
is missing (as opposed to being present, but
deleted), then //depot/proj1/file.c
is mapped into the workspace
instead.
Overlay mappings are useful for applying sparse patches in build environments.
Dealing with spaces in filenames and directories
Use quotation marks to enclose files or directories that contain spaces.
Example 10. 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: "//depot/Release 2.0/..." //joe/current/... "//depot/Release 1.1/..." "//joe/Patch Release/..." //depot/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.
Mapping 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: //depot/dev/... "//bruno_ws/c:/Current Release/..." //depot/release/... "//bruno_ws/d:/Prior Releases/..." //depot/www/... //bruno_ws/d:/website/...
Using the same workspace from different machines
By default, you can only use a workspace on the machine that is specified by the
Host:
field. If you want to use the same workspace on multiple machines
with different platforms, delete the Host:
entry and set the
AltRoots:
field in the client workspace specification. You can specify
a maximum of two alternate workspace roots. The locations must be visible from all machines
that will be using them, for example through NFS or Samba mounts.
Perforce 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 following example, if user bruno
's current working directory
is located under /usr/bruno
, Perforce uses the UNIX path as his
workspace root, rather than c:\bruno_ws
. This approach allows
bruno
to use the same client workspace 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 Configuring line-ending settings.
Automatically pruning empty directories from a workspace
By default, Perforce 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 Configuring workspace options.
Changing the location 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 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 workstation 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).
-
Change the
View:
field. -
Again, perform a p4 sync. The files in the client workspace are synced to their new locations.
Configuring workspace options
The following table describes workspace Options:
in detail.
Option |
Description |
Default |
---|---|---|
|
Specifies whether unopened files are always writable. By default, Perforce
makes unopened files read-only. To avoid inadvertently overwriting changes or
causing syncs to fail, specify A setting of If |
|
|
Specifies whether p4 sync overwrites writable but unopened workspace files. (By default, Perforce does not overwrite unopened files if they are writable.) If |
|
|
Specifies whether data is compressed when it is sent between your workstation and the Perforce service. |
|
|
Specifies whether other users can use, edit, or delete the client workspace
specification. A Perforce administrator can override the lock with the
If you lock your client workspace specification, be sure to set a password for the workspace's owner using the p4 passwd command. |
|
|
For files without the For files with the |
Ignored for files with the |
|
Specifies whether p4 sync deletes empty directories in a workspace if all files in the directory have been removed. |
|
Configuring 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 |
---|---|
|
All open files (with or without changes) are submitted to the depot. This is the default behavior of Perforce. |
|
All open files (with or without changes) are submitted to the depot, and all files are automatically reopened in the default changelist. |
|
Only those files with content, type, or resolved changes are submitted to the depot. Unchanged files are reverted. |
|
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. |
|
Only those files with content, type, or resolved changes are submitted to the depot. Any unchanged files are moved to the default changelist. |
|
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 |
Configuring 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 |
---|---|
|
Use mode native to the client (default) |
|
UNIX-style (and Mac OS X) line endings: |
|
Mac pre-OS X: |
|
Windows- style: |
|
The When you sync your client workspace, line endings are set to The most common use of the |
For detailed information about how Perforce uses the line-ending settings, see "CR/LF Issues and Text Line-endings" in the Perforce knowledge base:
http://answers.perforce.com/articles/KB_Article/CR-LF-Issues-and-Text-Line-endings
Deleting client workspace specifications
To delete a workspace, issue the p4 client -d
clientname
command. Deleting a client workspace
removes Perforce'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 workspace specification.
If you delete the workspace specification before you delete files in the workspace, you can delete workspace files using your operating system's file deletion command.
Security
For security purposes, your Perforce administrator can configure the Perforce service to require SSL-encrypted connections, user passwords, and to limit the length of time for which your login ticket is valid. The following sections provide details.
SSL-encrypted connections
If your installation requires SSL, make sure your P4PORT
is of the form
ssl:
.
If you attempt to communicate in plaintext with an SSL-enabled Perforce server, the
following error message is displayed:
hostname
:port
Failed client connect, server using SSL. Client must add SSL protocol prefix to P4PORT.
Set P4PORT
to
ssl:
,
and attempt to reconnect to the server.
hostname
:port
The first time you establish an encrypted connection with an SSL-enabled server, you are prompted to verify the server's fingerprint:
The authenticity of '10.0.0.2:1818' can't be established, this may be your first attempt to connect to this P4PORT. The fingerprint for the key sent to your client is CA:BE:5B:77:14:1B:2E:97:F0:5F:31:6E:33:6F:0E:1A:E9:DA:EF:E2
Your administrator can confirm whether the displayed fingerprint is correct or not. If
(and only if) the fingerprint is correct, use the p4 trust command to add
it to your P4TRUST
file. If P4TRUST
is unset, this file is
assumed to be .p4trust
in your home directory:
$ p4 trust The fingerprint of the server of your P4PORT setting 'ssl:example.com:1818' (10.0.0.2:1818) is not known. That fingerprint is CA:BE:5B:77:14:1B:2E:97:F0:5F:31:6E:33:6F:0E:1A:E9:DA:EF:E2 Are you sure you want to establish trust (yes/no)? Added trust for P4PORT 'ssl:example.com:1818' (10.0.0.2:1818)
If the fingerprint is accurate, enter yes
to trust this server. You
can also install a fingerprint directly into your trust file from the command line. Run:
p4 trust -p ssl:hostname
:port
-i fingerprint
where
ssl:
corresponds to your hostname
:port
P4PORT
setting, and
fingerprint
corresponds to a fingerprint that your
administrator has verified.
From this point forward, any SSL connection to ssl:example.com:1818
is trusted, so long as the server at example.com:1818
continues to report
a fingerprint that matches the one recorded in your P4TRUST
file.
If the Perforce server ever reports a different fingerprint than the one that you have trusted, the following error message is displayed:
******* WARNING P4PORT IDENTIFICATION HAS CHANGED! ******* It is possible that someone is intercepting your connection to the Perforce P4PORT '10.0.50.39:1667' If this is not a scheduled key change, then you should contact your Perforce administrator. The fingerprint for the mismatched key sent to your client is 18:FC:4F:C3:2E:FA:7A:AE:BC:74:58:2F:FC:F5:87:7C:BE:C0:2D:B5 To allow connection use the 'p4 trust' command.
This error message indicates that the server's fingerprint has changed from one that
you stored in your P4TRUST
file and indicates that the server's SSL
credentials have changed.
Although the change to the fingerprint may be legitimate (for example, your administrator controls the length of time for which your server's SSL credentials remain valid, and your server's credentials may have expired), it can also indicate the presence of a security risk.
Warning
If you see this error message, and your Perforce administrator has not notified you of a change to your server's key and certificate pair, it is imperative that you independently verify the accuracy of the reported fingerprint.
Unless you can independently confirm the veracity of the new fingerprint (by some out-of-band means ranging from the company's intranet site, or by personally contacting your administrator), do not trust the changed fingerprint.
Connecting to services that require plaintext connections
If your Perforce installation requires plaintext (in order to support older Perforce
applications), set P4PORT
to
tcp:
If you attempt to use SSL to connect to a service that expects plaintext connections, the
following error message is displayed:
hostname
:port
.
Perforce client error: SSL connect to ssl:host
:port
failed (Connection reset by peer). Remove SSL protocol prefix from P4PORT.
Set P4PORT
to
tcp:
(or, if you are using applications at release 2011.1 or earlier, set hostname
:port
P4PORT
to
),
and attempt to reconnect to the service.
hostname
:port
Passwords
Depending on the security level at which your Perforce installation is running, you
might need to log in to Perforce before you can run Perforce commands. Without passwords,
any user can assume the identity of any other Perforce user by setting P4USER
to a different user name or specifying the -u
flag when you issue a
p4 command. To improve security, use passwords.
Setting passwords
To create a password for your Perforce user, issue the p4 passwd command.
Passwords may be up to 1024 characters in length. Your system administrator can configure Perforce to require "strong" passwords, the minimum length of a password, and if you have been assigned a default password, your administrator can further require that you change your password before you first use Perforce.
By default, the Perforce service defines a password as strong if it is at least eight characters long and contains at least two of the following:
-
Uppercase letters
-
Lowercase letters
-
Non-alphabetic characters
In an environment with a minimum password length of eight characters, for example,
a1b2c3d4
, A1B2C3D4
, aBcDeFgH
would be considered strong passwords.
To reset or remove a password (without knowing the password), Perforce superuser privilege is required. If you need to have your password reset, contact your Perforce administrator. See the Perforce Server Administrator's Guide: Fundamentals for details.
Using your password
If your Perforce user has a password set, you must use it when you issue p4 commands. To use the password, you can:
-
Log into Perforce by issuing the p4 login command, before issuing other commands
-
Set
P4PASSWD
to your password, either in the environment or in a config file -
Specify the
-P
flag when you issue p4 commands (for instance, p4 -Ppassword
mypassword
submit) -
Windows or OS X: store your password by using the p4 set -s command. Not advised for sites where security is high. Perforce administrators can disable this feature.
Connection time limits
Your Perforce administrator can configure the Perforce service to enforce time limits for users. Perforce uses ticket-based authentication to enforce time limits. Because ticket-based authentication does not rely on environment variables or command-line flags, it is more secure than password-based authentication.
Tickets are stored in a file in your home directory. After you have logged in, your ticket is valid for a limited period of time (by default, 12 hours).
Logging in and logging out
If time limits are in effect at your site, you must issue the p4 login command to obtain a ticket. Enter your password when prompted. If you log in successfully, a ticket is created for you in the ticket file in your home directory, and you are not prompted to log in again until either your ticket expires or you log out by issuing the p4 logout command.
To see how much time remains before your login expires, issue the following command:
p4 login -s
If your ticket is valid, the length of time remaining is displayed. To extend a ticket's lifespan, use p4 login while already logged in. Your ticket's lifespan is extended by 1/3 of its initial timeout setting, subject to a maximum of your ticket's initial timeout setting.
To log out of Perforce, issue the following command:
p4 logout
Working on multiple machines
By default, your ticket is valid only for the IP address of the machine from which you logged in. If you use Perforce from multiple machines that share a home directory (typical in many UNIX environments), log in with:
p4 login -a
Using p4 login -a creates a ticket in your home directory that is valid from all IP addresses, enabling you to remain logged into Perforce from more than one machine.
To log out from all machines simultaneously, issue the following command:
p4 logout -a
For more information about the p4 login and p4 logout commands, see the P4 Command Reference.
Working with Unicode
The Perforce service can be run in Unicode mode to activate support for file names or directory names that contain Unicode characters, and Perforce identifiers (for example, user names) and specifications (for example, changelist descriptions or jobs) that contain Unicode characters.
In Unicode mode, the Perforce service also translates unicode
files
and metadata to the character set configured on the user's workstation, 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 above, you do not need to run Perforce in Unicode mode. Your system administrator will tell you if your site is using Unicode mode or not.
For these installations, assign the Perforce 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 interoperate in Unicode mode, and to ensure that such files are translated
correctly by the Perforce service when the files are synced or submitted, you must set
P4CHARSET
to the character set that corresponds to the format used on your
workstation by the applications that access them, such as text editors or IDEs. These formats
are typically listed when you save the file using the
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 Perforce Server Administrator's Guide: Fundamentals.
Setting P4CHARSET on Windows
To set P4CHARSET
for all users on a workstation, you need Windows
administrator privileges. Issue the following command:
p4 set -s P4CHARSET=character_set
To set P4CHARSET
for the user currently logged in:
p4 set P4CHARSET=character_set
Your workstation 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 |
Set |
---|---|
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
.