Build Checkout Directory
The build checkout directory is a directory on the TeamCity agent machine where all of the sources of all builds are checked out into. If you use the VCS Checkout Mode, the build agent checks out the sources into this directory before the build. In case you use the VCS Checkout Mode, the 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; however, the default (empty) value is highly recommended. See Custom-checkout-directory.
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 < >/directory.map generated file which lists build configurations with the directories they used last.
In your Build Script Interaction with TeamCity you can refer to the effective value of the build checkout directory via the teamcity.build.checkoutDir Configuring Build Parameters provided by TeamCity.
By default, this is also the directory Build Working Directory.
Checkout Process
For checkout handled by TeamCity (the VCS Checkout Mode or VCS Checkout Mode 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 Working with Build Results 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:
make sure the builds perform a clean procedure as the first step of the build for all the files that affect the build and might have been produced by previous builds. Typical files are compilation output, tests reports, build produce artifacts.
make sure the builds never modify or delete the files under version control
If TeamCity detects that it cannot build an incremental patch, Clean Checkout in enforced. It can also be enforced manually or configured to be performed on each build.
Custom checkout directory
In most cases, leaving the checkout directory with the default value (empty in UI) is recommended. 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: < >/<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:
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 in the directory);
the content of the directory is not modified by processes other than those of 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 the 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, the other agent is appearing as an external process to it.
Note that content of the checkout directory can be deleted by TeamCity under Clean Checkout.
Automatic Checkout Directory Cleaning
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). ( See ensuring Free disk space when the checkout directory can be cleaned automatically.)
The time frame for automatic directory expiration can be changed by specifying a new value (in hours) by either of the following ways:
'teamcity.agent.build.checkoutDir.expireHours'Project and Agent Level Build Parameters in thebuildAgent.propertiesfile;'system.teamcity.build.checkoutDir.expireHours'Configuring Build Parameters
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.
The directory cleaning is performed in the background and can be paused by consequent builds.