Build Checkout Directory
The build checkout directory is a directory on the TeamCity agent machine where the build sources from a specific VCS root are checked out. This directory can be shared between multiple build configurations, if the build configurations are configured with the same VCS root. For more details, see Default Checkout Directory and Custom Checkout Directory.
Checkout Process
The checkout process is affected by the VCS Checkout Mode, as follows:
If you use the agent-side checkout mode, the build agent checks out the sources into the build checkout directory before the build.
If you use the server-side checkout mode, the TeamCity server sends incremental patches to the agent to update only the files changed since the last build in the given checkout directory.
If you use the manual checkout mode, no sources will be checked out, but the default build checkout directory will still be created to check out the sources using a build script. The directory will not be cleaned automatically unless its expiration period is configured as described below.
For checkout handled by TeamCity (the server-side or agent-side checkout mode), TeamCity keeps track of the last revision checked out in 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 (for example, 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, a clean checkout is enforced. It can also be enforced manually or configured to be performed on each build.
Checkout Directory Location
Default Checkout Directory
The default checkout directory location (when Checkout directory field is set to Auto in the build settings Version Control Settings page) is given by:
If the location of the agent work directory is customized, this changes to:
The VCS settings hash code, <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.
Source files are placed in the checkout directory according to the mapping defined in the VCS Checkout Rules.
Custom Checkout Directory
To configure a custom checkout directory, set the Checkout directory field to Custom path in the build settings Version Control Settings page and enter the custom path in the field provided.
Make sure the following conditions are satisfied:
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 appears as an external process to it.
Note that the content of the checkout directory can be deleted by TeamCity under certain circumstances.
Finding a Checkout Directory
If you are investigating 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 consult the generated file, <Agent_Work_Dir>/directory.map, which lists build configurations together with the directories they used last.
In your build script, you can refer to the effective value of the build checkout directory using the teamcity.build.checkoutDir property provided by TeamCity. By default, this is also the directory where builds run.
Checkout Directory Expiration
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 the 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 that the build gets enough disk free space on the build agent.
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.expireHoursagent property in thebuildAgent.propertiesfilesystem.teamcity.build.checkoutDir.expireHoursbuild configuration property0will cause deleting the checkout directories right after the build finishesneverwill let TeamCity know that the directory should never be deleted by TeamCitydefaultwill enforce using the default value
Expiration-based directory cleaning is performed in the background when build agent is idle (that is, no builds are running).
The lifetime of a checkout directory is reflected in the work/directory.map file. Rows in the file correspond to existing checkout directories (one to one). Last value in each row represents the number of hours before that particular directory is cleaned up. By default, the value is set to 192 hours (8 days) for each directory (parameter value: default).
You can override the default value by specifying the abovementioned parameters, but bear in mind that the change will only apply to all newly created directories, meaning that all existing directories will retain their respective lifetime values.