TeamCity On-Premises 2024.03 Help

Build Files Cleaner (Swabra)

Swabra is a bundled TeamCity plugin that allows you to add the Swabra build feature to your build configurations. This build feature allows you to do the following:

  • Remove files generated during a build. The feature creates a list of all files in the checkout directory after the sources checkout is complete. After a build finishes (or before the next build starts), files that are not on this list are automatically removed.

  • Detect files modified or deleted during the build. Such files are reported to the build log (however, deleted files are not restored). This allows you to ensure your new builds do not start with certain source files deleted or modified by previous builds, and initiate a clean checkout if this is the case.

  • Dump processes that lock directory by the end of the build (requires handle.exe).

Swabra saves the checkout directory state to the <checkout-directory-name-hash>.snapshot file in the caches directory using the DiskDir format. The path to the checkout directory to be cleaned is stored in the file. The snapshot stores information about existing files, their last modification and size. This information is used when a build finishes (or a new build is about to start) to identify changes.

Configuring Swabra Options



Files clean-up

Select whether you want to perform build files clean-up, and when it will be performed.

Clean checkout

Select the Force clean checkout if cannot restore clean directory state option to ensure new builds utilize source files that fully match those stored in the remote repository. If Swabra detects files in the checkout directory that were modified or deleted, it enforces the clean checkout. If Swabra cannot remove any leftover files created by a previous build, the current build will fail.

If this option is disabled, Swabra displays warnings when it finds modified and deleted files, but does not trigger the clean checkout.

Paths to monitor

Specify a newline-separated set of +:path (to include) and -:path (to exclude) rules to specify files and directories Swabra should watch. By default, the entire checkout directory is monitored. The path can be relative to the build's checkout directory or absolute, and can include Ant-like wildcards. If no +: or -: prefix is specified, a rule as treated as "include".

Rules should be arranged according to their explicitness: less specific rules that point to directories and use wildcards should be placed above more targeted rules that point to individual files. The first rule should always point to a directory.

Swabra is case-sensitive.


  • -:*/dir/* excludes all dir directories and their content

  • -:some/dir, +:some/dir/inner excludes the some/dir directory and all its content except for the inner subdirectory and its content

  • +:./*file.txt includes only the specified file in the build checkout directory into monitoring

  • -:file.txtexcludes the specified file in the build checkout directory from monitoring

Locking processes

Select whether Swabra should search for processes that lock checkout directory files, and how it should handle such processes. Note that Swabra requires handle.exe installed on agents to detect such processes.

Verbose output

Check this option to enable detailed logging to the build log.

Default excluded paths

If a build employs the agent checkout, Swabra ignores all .svn, .git, .hg, CVS directories and their content. To disable this behaviour, specify an empty swabra.default.rules configuration parameter.

Installing Handle

You can install handle.exe from the Administration | Tools page.
Click the Install Tool button and select Sysinternals handle.exe from the list of tools.
Specify whether you want to download the latest version of handle.exe or upload it manually choosing the path on local machine, and click Add. After the TeamCity server downloads or uploads handle.exe, it sends this tool to Windows agents during a scheduled upgrade.

Note that running handle.exe requires administrator privileges for the build agent user.

Debug options

Generally snapshot file is deleted after files collection. Set the swabra.preserve.snapshot system property to preserve snapshots for debugging purposes.

Clean Checkout

Note that Swabra may sometimes cause clean checkout to restore clean checkout directory state.
To avoid unnecessary frequent clean checkouts, always set up identical Swabra build features for build configurations working in the same checkout directory.
Build configurations work in the same checkout directory if either the same custom checkout directory path or same VCS settings configured for them.

Last modified: 11 April 2024