This section concerns only the latest version of the plugin.

General Info

Vendor

JetBrains

License

Apache 2.0

Type

free, open-source

Plugin Description

Plugin adds support for cleaning new files created during the build. The files modified or deleted during the build are also reported in the build log (but are not affected by the plugin).

The plugin remembers the state of the file tree after the sources checkout and on next build start deletes all the newly added files.

Plugin can also ensure clean checkout directory and at the build start initiate clean checkout if there are any modified or deleted in the checkout directory.

The plugin also gives the ability to dump processes which lock the checkout directory before build finish (requires handle.exe)

Plugin Development Status

In final stage of development. Snapshot builds are available.
Everyone is encouraged to try the plugin.

TeamCity Versions Compatibility

Plugin was bundled with TeamCity 5.1.
In TeamCity 6.0 Swabra became a build feature.

Documentation

Installation instructions

  1. Put swabra.zip into <TeamCity Data Directory>/plugins folder.
  2. Restart the server.

Plugin usage

The plugin can be used with any runners. Swabra tab provides UI options to enable scanning checkout directory for newly created, modified and deleted files and for enabling file locking processes detection.

Checkout directory state is saved into a file in the caches directory named <checkout_directory_name_hash>.snapshot using DiskDir format. Checkout directory to snapshot name map is saved into snapshot.map file. The snapshot is used later (at the start of the next build) to determine which files and folders are newly created, modified or deleted. It is done by actual files' presence, last modification data and size comparison with corresponding records in the snapshot.

–°onfiguring plugin via UI options

For TeamCity 6.0

The plugin can be configured as a build feature from Build Steps page.

Choose suitable Files cleanup mode which can be After build finish or Before next build start.

Use Clean checkout to ensure that the checkout directory corresponds to the sources in the repository at the build start. If detecting any modified or deleted files in the checkout directory before the build start Swabra will enforce clean checkout. The build will also fail if some newly created during previous build files can't be deleted.

Use Paths to monitor setting to specify newline or comma delimited set of +|-:checkout_dir_relative_path rules.

Select Locking processes mode to inspect the checkout directory for processes locking files in this directory.
Choose Report or Kill mode to get report about such processes in the build log or kill them.
Note that for locking processes detection handle.exe is required on agents. Click the Insatall SysInternals handle.exe link for downloading or uploading.

Check Verbose output option to enable detailed logging to build log.

For TeamCity 5.1.x

The plugin adds its configuration settings panel to the runner settings page.

Check Perform build files cleanup option to enable build files cleanup.

Use Ensure clean checkout directory to ensure that the checkout directory corresponds to the sources in the repository at the build start. If detecting any modified or deleted files in the checkout directory before the build start Swabra will enforce clean checkout. The build will also fail if some newly created during previous build files can't be deleted.

Without Ensure clean checkout directory you will only get warnings about modified and deleted files.

Use Cleanup rules setting to specify newline or comma delimited set of +|-:checkout_dir_relative_path rules.

Select Locking processes mode to inspect the checkout directory for processes locking files in this directory.
Choose Report or Kill mode to get report about such processes in the build log or kill them.
Note that for locking processes detection handle.exe is required on agents. Click the Insatall SysInternals handle.exe link for downloading or uploading.

Check Verbose output option to enable detailed logging to build log.

Paths to monitor

How to use

These rules tell Swabra what files and folders should be involved in files collection process.
If no +: or -: prefix is specified rule as treated as include.
A path can be checkout directory relative path or a mask with ant-style wild cards.

By default all paths are included.
Ignoring a directory leads to ignoring the whole it's content.
Rules on any path should come in order from more abstract to more concrete, e.g. use -:*/dir/* to exclude all dir folders and their content,
or -:some/dir, +:some/dir/inner to exclude some/dir folder and all it's content except inner subfolder and it's content.

Note that after removing some exclude rules it's advisable to run clean checkout.

Default excluded paths

If the build is set up to checkout on agent swabra by default ignores all .svn, .git, .hg, CVS folders and their content.
To turn off this behaviour specify empty swabra.ignored.paths system.property.

Downloading Handle

Specify URL for downloading handle.exe or download it manually and specify path on local machine, press Download button and TeamCity will automatically download or upload handle.exe and send to Windows agents.

handle.exe will be present on agents only after the upgrade process.
Note that you need to have enough permissions to start the download.

You may also download Handle, extract it on agent and set up the handle.exe.path system property manually.

You should also remember that running handle.exe requires some additional permissions for the build agent user. For more details please read this thread.

Debug options

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


h3. Known Issues

Feedback/Support

If you believe you've faced a bug: Issue Tracker (project: TeamCity)
If you want to ask a question or discuss: Forum

Development links

Sources in JetBrains Subversion repository.
Builds for TeamCity 5.x and
Builds for TeamCity 5.0.x and
Builds for TeamCity 4.5.x at JetBrains public TeamCity

Related Materials

Issue in TeamCity tracker.