Build Checkout Directory

The build checkout directory is the directory on agent where all of the project's sources reside. If you use VCS Checkout Mode, build agent checks out the sources into this directory before the build. In case you use VCS Checkout Mode, TeamCity server sends to the agent incremental patches to update only the files changed since the last build in the given checkout directory. The sources are placed into the checkout directory according to the mapping defined in the VCS Checkout Rules.

You can specify the checkout directory when configuring Checkout Settings on the Configuring VCS Roots page. If not specified, automatically created directory is used with a generated name: < >/<VCS settings hash code>. The VCS settings hash code is calculated based on VCS roots and VCS settings used by the build configuration. Effectively, this means that the directory is shared between all the build configurations with the same VCS settings.

If you want to investigate some issue and need to know the directory used by a build configuration, you can get the directory from the build log, or you can refer to < >/directory.map generated file which lists build configurations with their last used directories.

If for some reason default directory does not match your requirements (for example, the process of creating builds depends on some particular directory), you may want to Configuring VCS Settings.

note

Please ensure that the checkout directory is not shared between build configurations with different VCS settings. Please also ensure that the content of the directory is not modified by other processes. Otherwise, the directory content may get out of sync with the state TeamCity think it is in and the files may not be updated to the state necessary for a build. In this case Clean Checkout will be necessary.

Please note that content of the checkout directory can be deleted by TeamCity under Clean Checkout.

As a kind of failover measure TeamCity automatically performs Clean Checkout, if it finds files of another build configuration in the current checkout directory or the directory is empty.

In your Build Script Interaction with TeamCity you may refer to the effective value of build checkout directory via the teamcity.build.checkoutDir Configuration and Build Parameters provided by TeamCity.

Automatic Checkout Directory Cleaning



Checkout directories are automatically deleted from disk if not used (no builds use it as checkout directory) for a specified period of time (8 days by default). This behavior only applies to checkout directories created under the agent work directory (i.e. default checkout directories and custom checkout directories defined using relative paths).

The time frame can be changed by specifying new value (in hours) by either of the following ways:

• 'teamcity.agent.build.checkoutDir.expireHours' Other Ways to Define Build Parameters in the buildAgent.properties file;

• 'teamcity.build.checkoutDir.expireHours' Configuration and Build Parameters

Setting the property to "0" will cause deleting the checkout directories right after the build finish.

The directory cleaning is performed in background and can be paused by consequent builds.

Ensuring Free Disk Space Before the Build



Before the build is run on the agent, TeamCity checks the available free space. If build agent does not have required free disk space, build agent tries to free the disk space by

• forcing delete of obsolete Checkout Directories that were pushed to background (see previous section);

• deleting contents of other build's checkout directories in the reverse Most Recently Used order. Only default checkout directories can be cleaned. Custom checkout directories are not cleaned.

The disk space check is performed for two locations: Agent Home Directory and build checkout directory.

By default, the required free space is 3Gb. You can specify the free space value for a build agent in its buildagent.properties file or change the default value for a particular build configuration by specifying its system properties.

Required free space value is defined by the following properties:

• system.teamcity.agent.ensure.free.space for build checkout directory.

• system.teamcity.agent.ensure.free.temp.space for agent's 'temp' directory. If teamcity.agent.ensure.free.temp.space is not defined, the value of teamcity.agent.ensure.free.space property is used.

The values of the properties specifies size of the free disk space to clean before the build start. The value should be a number followed by kb, mb, gb, kib, mib, or gib suffix. Use no suffix for bytes. e.g. system.teamcity.agent.ensure.free.space = 5Gb