Skip to end of metadata
Go to start of metadata
You are viewing documentation of TeamCity 6.5.x, which is not the most recent released version of TeamCity. Please refer to the listing to choose another version.

Table of Contents

The build checkout directory is the directory on agent where all of the project's sources reside. If you use agent-side checkout mode, build agent checks out the sources into this directory before the build. In case you use server-side 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 Version Control Settings page, however, default (empty) value is recommended. See #Custom checkout directory.
If not specified, automatically created directory is used with a generated name: <Agent Work Directory>/<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 <Agent Work Directory>/ generated file which lists build configurations with their last used directories.

In your build script you may refer to the effective value of build checkout directory via the property provided by TeamCity.

Custom checkout directory

In the most cases, leaving the checkout directory with default value (empty in UI) is recommended.
With this default checkout directory TeamCity ensures best performance and consistent incremental sources updates.

If for some reason you need to specify custom checkout directory (for example, the process of creating builds depends on some particular directory), please ensure that the following conditions are met:

  • the checkout directory is not shared between build configurations with different VCS settings (otherwise TeamCity will perform clean checkout each time another build configuration is built int he directory);
  • the content of the directory is not modified by other processes than a single TeamCity agent (otherwise TeamCity might be unable to ensure consistent incremental sources update). If this cannot be eliminated, make sure to turn on clean build checkout option for all the participating build configurations. This rule also applies to two TeamCity agents sharing the same working directory. As one TeamCity agent has no knowledge of another, another agent is appearing as an external process to it.

Please also note that content of the checkout directory can be deleted by TeamCity under certain circumstances.

Automatic Checkout Directory Cleaning

Checkout directories are automatically deleted from disk if not used (no builds were run on the agent using the directory as checkout directory) for a specified period of time (8 days by default).
(Please also see ensuring free disk space case when the checkout directory can be cleaned automatically.)

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

Setting the property to "0" will cause deleting the checkout directories right after the build finish.
Setting the property to "never" will let TeamCity know that the directory should never be deleted by TeamCity.
Setting the property to "default" will enforce using the default value.

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

See also:

Administrator's Guide: Configuring VCS Settings