Clean Checkout

Enforcing Clean Checkout

Clean checkout is recommended if the checkout directory content was modified by an external process by adding new, modifying or deleting existing files.

You can enforce the Clean Sources action:

• for a build configuration — from the Build Configuration Home page, using the Actions drop-down menu in the upper right corner.

• for an agent — from the Agent Details page, using the Miscellaneous section, the Clean sources on this agent option.

The action opens a list of agents/build configurations to clean sources for.

The Clean Sources is a single action that, after triggered, is performed only once during the next build run of each selected configuration on each selected agent.

TeamCity maintains an internal cache for the sources to optimize communications with the VCS server. The caches are reset during the clean-up. To resolve problems with sources update, the caches may need to be reset manually using the Diagnostics | Caches tab in the UI or by deleting the <TeamCity Data Directory>/system/caches directory.

Automatic Clean Checkout

You can also enable automatic cleaning the sources before every build, if you check the option Clean all files before build on the Create/Edit Build Configuration> Version Control Settings page. If this option is checked, TeamCity performs a full checkout before each build. If clean checkout is not enabled, TeamCity updates the sources in the checkout directory incrementally to the required state.

TeamCity tries to detect if the sources in the checkout directory are not corresponding to the expected state and triggers clean checkout in such cases to ensure sources are appropriate. This means that under certain circumstances TeamCity can detect clean checkout is necessary even if it is not enabled in the VCS settings and not requested by the user from web UI. In such cases, all the content of the checkout directory is deleted and it is repopulated by the sources from scratch. If any details are available on the decision, they are added into the build log before checkout-related logging.

Here is the summary of cases when TeamCity performs automatic clean checkout:

• if it is enabled using the Clean all files in the checkout directory before the build option in the "Version Control Settings" of the build configuration

• build checkout directory was not found or is empty (either the build configuration is started on the agent for the first time or the directory has disappeared since the last build). This also covers the following:

  • no builds were run in a specific checkout directory for a configured (or default) time and the directory became empty. See more at automatic checkout directory cleaning

  • there was not enough free space on disk in one of the earlier builds and the directory was deleted

• a user invoked "Enforce clean checkout" action from the web UI for a build configuration or agent

• the build was triggered via Custom Run Build dialog with "Clean all files in the checkout directory before build" option selected or by a trigger with the corresponding option

• the build was triggered by a Schedule trigger with "Clean all files in checkout directory before build" option enabled or as a part of a build chain where the topmost build was triggered with the setting in the schedule trigger while "apply to all snapshot dependencies" was also selected

• VCS settings of the build configuration were changed

• the previous build in this directory was of a build configuration with different VCS settings (can only occur if the same checkout directory is specified for several build configurations with individual VCS settings and VCS Roots)

• the previous build in this directory was built on more recent revisions than the current one (can only occur for history builds)

• there was a critical error while applying or rolling back a patch during the previous build, so TeamCity cannot ensure that checkout directory contains known versions of files

• Build Files Cleaner (Swabra) is enabled with corresponding options and it detected that clean checkout is necessary

• Custom checkout directory contains agent-specific parameters, such as %teamcity.agent.work.dir% (pre-8.1)