Unable to render embedded object: File (TeamCity48.png) not found.

TeamCity 2018.x Documentation

[Documentation for Previous Versions]


You are viewing the documentation of TeamCity 2018.x, which is not the most recently released version of TeamCity.
View this page in the latest documentation or refer to the [listing] to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

This page contains descriptions of the fields and options available when setting up VCS roots using Perforce.
Common VCS Root properties are described here.


A Perforce client must be installed on the TeamCity server and it should be present in PATH. Alternatively, a full path to p4 could be set via internal property teamcity.perforce.customP4Path.

If you plan to use the agent-side checkout mode, note that a Perforce client must be installed on the agents, and the path to the p4 executable must be added to the PATH environment variable.

Also check TeamCity and Perforce compatibility.

P4 Connection Settings




Specify the Perforce server address. The format is host:port.
(info) For specific environments, P4Host can be specified in the Workspace options below for any  type of checkout. 


Click this radio button to specify an existing Perforce stream. TeamCity will use this stream to prepare the stream-based workspace, and will use the client mapping from such a workspace.

TeamCity supports deeper directory structure within the root depot: depots with a depth of //DEPOTNAME/1/2/n can be specified in this field.
Prior to TeamCity 2017.2, TeamCity supports streams stored one level below the depot name: the format is //streamdepot/streamname.

 Parameters are supported. For the StreamAtChange option, use the Label to checkout field.

Performance impact


When this option is used with the checkout on the server mode, the internal TeamCity source caching on the server side is disabled, which may worsen the performance of clean checkouts. Also, with this option, snapshot dependencies builds are not reused. (TW-41898 - fixed in TeamCity 2017.1)

Checkout rules limitations


When Perforce Streams are used with the checkout on the agent, simple checkout rules like . => sub/directory are supported. Exclude checkout rules, multiple include rules, or rules like aaa=>bbb are not supported.

Enable feature branches support (experimental) - select this check box to specify branch streams you want to be monitored for changes in addition to the default one. Enter / Edit the branch specification as a newline-delimited set of rules. The syntax is  +|-:stream_name (with the optional * placeholder). 

Task stream limitations


When task streams are used for feature branches, TeamCity may miss some changes in task streams until a modifying commit is made, which means that merge commits from the parent stream are not detected until a 'real' commit to the task stream is made (TW-44765).


Click this radio button to directly specify the client workspace name. The workspace must be already created by a Perforce client application like P4V or P4Win. Only the mapping rules from the configured client workspace are used. The client name is ignored.

Performance impact


When this option is used with the checkout on the server mode, the internal TeamCity source caching on the server side is disabled, which may worsen the performance of clean checkouts. Also, with this option, snapshot dependencies builds are not reused. (TW-41898 - fixed in TeamCity 2017.1)

Client Mapping

Click this radio button to specify the mapping of the depot to the client computer.
If you have Client mapping selected, TeamCity handles file separators according to the OS/platform of the build agent where a build is run. To enforce specific line separator for all build agents, use Client or Stream with the LineEnd option specified in Perforce instead of Client mapping. Alternatively, you can add an agent requirement to run builds only on a specific platform.



Use team-city-agent instead of the client name in the mapping.


(warning) Prior to TeamCity 10.0 editing the client mapping for a Perforce VCS root resulted in a Clean Checkout before the next build. A workaround was provided.

Now Clean Checkout on a client mapping change is not enforced for the agent-side checkout in the following cases:

  • when a Perforce client name is used. Changing the Perforce client mapping for the client will not result in a clean checkout
  • when a Perforce stream is used, changing the stream name while keeping the same stream root will not result in a clean checkout

(warning) If the direct client mapping is changed, a clean checkout will be forced unless the teamcity.perforce.enable-no-clean-checkout internal property is set on the server.


Specify the user login name.

Password or Ticket

Specify the password or ticket.

Ticket-based authentication


Check this option to enable ticket-based authentication. (info) This option is enabled by default and not displayed.

Case-Insensitivity in Checkout Rules


Note that Perforce support in TeamCity treats checkout rules as case-sensitive. Case-insensitivity for Perforce-based build configurations can be enabled on the VCS settings page by adding the following comment in the Edit Checkout Rules field:

 ##teamcity ignore-case 

Checkout On Agent Settings

When the agent-side checkout is used, TeamCity creates a Perforce workspace for each checkout directory/VCS root. These workspaces are automatically created when necessary and are automatically deleted after some idle time.
It is possible to customize the name generated by TeamCity: add the teamcity.perforce.workspace.prefix configuration parameter at the Parameters page with the prefix in the value.



Workspace options

If needed, you can set here the following options for the p4 client command: Options, SubmitOptions, and LineEnd.
(info) For specific environments, P4Host can be specified here for any  type of checkout.  

Run 'p4 clean' for cleanup

Enable this option to clean up your workspace from extra files before a build (since p4 2014.1) When enabled, the p4 clean command will be run before p4 sync command, unless p4 sync -f or p4 sync -p is used. See the p4 sync command reference.

Skip the have list update:

Enable this option not to track files on the Perforce server on sync (always transfer all files to the agent, p4 sync -p)

Extra sync options

Specify additional 'p4 sync' options, like --parallel. See p4 sync command reference.

Perforce Workspace Parameters

With checkout on agent, TeamCity provides environment variables describing the Perforce workspace created during the checkout process.
If several Perforce VCS Roots are used for the checkout, the variables are created for the first VCS root.
The variables are:

  • P4USER - same as vcsroot.<VCS root ID>.user parameter
  • P4PORT - same as vcsroot.<VCS root ID>.port parameter
  • P4CLIENT - name of the generated P4 workspace on the agent

These variables can be used to perform custom p4 commands after the checkout.

More information: Perforce Workspace Handling in TeamCity

Perforce Proxy Settings

To allow using Perforce proxy with the agent-side checkout, specify the env.TEAMCITY_P4PORT environment variable on the build agent and the agent will take this value as the P4PORT value.

Other Settings

P4 path on the build agent


Specify the path to the Perforce command-line client: p4.exe file.

This field works only on the agent side for agent-side checkout (prior to TeamCity 2017.2.2 this path was be used for both the server-side checkout and the agent-side checkout).
For the server, the p4 binary should be present in the PATH of the TeamCity server or can be specified via the teamcity.perforce.customP4Path internal property). 

To restore old behavior, the teamcity.perforce.p4PathOnServerWhitelist internal property can be used to specify a  semi-colon-separated list of allowed p4 paths.

Label/changelist to sync

If you need to check out sources not with the latest revision, but with a specific Perforce label (with selective changes), you can specify this label here. For instance, this can be useful to produce a milestone/release build, or a reproduce build. If the field is left blank, the latest changelist will be used for sync.


It is recommended to use the agent-side checkout if you use symbolic labels. With the server-side checkout on label, TeamCity will perform full checkout.


Select the character set used on the client computer.

Support UTF-16 encoding

Enable this option if you have UTF-16 files stored as utf16 Perforce file type in your project.

You may want to enable this option if you use server-side checkout and have files of the utf16 Perforce file type in your depot. Enable this flag for the checked out files to be in the UTF-16 encoding. Otherwise, such files may be converted to UTF-8 upon checkout.

If you store UTF-16 files as the binary Perforce file type, they will always be checked out "as is", no conversion will be performed.

Perforce Jobs Support

For a changelist which was checked in with one or several associated jobs, TeamCity shows a wrench icon  which allows you to view details of the jobs when clicked or hovered over.  


All Perforce plugin operations are logged into teamcity-vcs.log files with category jetbrains.buildServer.VCS.P4 (on an agent or on a server, depending on the operation context). The detailed logging can be enabled with debug-vcs preset.

Perforce Workspace Handling in TeamCity

Please refer to a separate page.

Perforce VCS Compatibility

Please refer to a separate page.

Perforce Streams as feature branches

Please refer to a separate page.

See also:

Administrator's Guide: VCS Checkout Mode




















  • No labels