You are viewing the documentation of TeamCity 9.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata

Clean Checkout (also referred to as "Clean Sources") is an operation that ensures that the next build will get a copy of the sources fetched all over from the VCS. All the content of the Build Checkout Directory is deleted and the sources are re-fetched from the version control.

Enforcing Clean Checkout

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

You can enforce clean sources action for a build configuration from the Build Configuration home page (Actions drop-down in the top right corner), or for an agent from the Agent Details page. The action opens a list of agents/build configurations to clean sources for.

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 you set specific folder as the Build Checkout Directory (instead of using default one), you should remember that all of the content of this directory will be deleted during clean checkout procedure.


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

Automatic Clean Checkout

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 re-populated by the sources from scratch.
If any details are available on the decision, they are added into the build log before checkout-related logging.

TeamCity performs automatic clean checkout in the following cases:

  • 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
    • particularly when 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.
    • particularly when there were 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 checkout directory before build" option selected or by a trigger with corresponding option
  • 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 then 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)

Clean checkout is performed each time if "Clean all files in the checkout directory before the build" option is ON in "Version control settings" of the build configuration.

Also, there are cases when agent can delete the build checkout directory e.g. when it expires or to meet free disk space requirements.