On this page:

The build checkout directory is a directory on the TeamCity agent machine where all of the sources of all builds are checked out into.

The sources are placed into the checkout directory according to the mapping defined in the VCS Checkout Rules.

The checkout directory is configured in the Checkout Settings section on the Version Control Settings page; the default Auto (recommended) value is strongly advised, but it is possible to configure a custom checkout directory as described below.

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

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

(info) By default, this is also the directory where builds will run.

Checkout Process

For checkout handled by TeamCity (the server-side or agent-side checkout mode), TeamCity keeps track of the last revision checked out into each checkout directory on the agent and for the new build applies an incremental patch from the last used revision to the revision of the current build.
The revisions used can be looked up on the Changes tab of the build results page.

Incremental checkouts mean that any files not created or modified by TeamCity (e.g. by the previous build scripts) are preserved in their modified state (unless dedicated VCS root-specific reset options are used).
That is why it is recommended to:

If TeamCity detects that it cannot build an incremental patch, a clean checkout in enforced. It can also be enforced manually or configured to be performed on each build.

Custom checkout directory

In most cases, the default Auto (recommended) setting will cover your needs. With this default checkout directory TeamCity ensures best performance and consistent incremental sources updates. The name of the default automatically created directory is generated as follows: <Agent Work Directory>/<VCS settings hash code>. The VCS settings hash code is calculated based on the set of VCS roots, their checkout rules and VCS settings used by the build configuration (checkout mode). Effectively, this means that the directory is shared between all the build configurations with the same VCS settings.

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

(warning) Note that content of the checkout directory can be deleted by TeamCity under certain circumstances.

Automatic Checkout Directory Cleaning

With the server-side and agent-side checkout modes, checkout directories are automatically deleted from the disk if not used (no builds were run on the agent using the directory as the checkout directory) for a specified period of time (8 days by default) or when another build requires more free disk space than available. With manual checkout mode, automatic directory cleaning is not performed unless the directory expiration period is configured.

It is recommended to use the Free disk space build feature to ensure the build gets enough disk free space on the build agent.

{hidden-data}old section name for obsolete anchors:{hidden-data}

There are also obsolete manual controls for old checkout directories cleanup:

The time frame for automatic directory expiration can be changed by specifying a 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 finishes.
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.

Expiration-based directory cleaning is performed in the background when the build agent is idle (no builds are running).


See also:

Administrator's Guide: Configuring VCS Settings