What is FilteredSourceControl?

The FilteredSourceControl allows you to filter out modifications that are used to trigger a build. If for example, you have certain files (such as web pages or document files) under source control that you don't want to have trigger the build, you can use this class to ensure that their changes will keep a new build from launching.

The FilteredSourceControl works together with all of the source controls supported by CCNet (including the Multi Source Control Block). It can also be included under the Multi Source Control Block provider so that you could have multiple FilterSourceControls each filtering a different set of modifications from different source control providers. Essentially, it acts as a decorator (or an example of the pipes and filters pattern ), wrapping around the specific SourceControl provider that you want to use.

The FilteredSourceControl includes both inclusion and exclusion filters for specifying what modifications should be included/excluded. Multiple inclusion and exclusion filters can be specified or, alternately, no inclusion or exclusion filter could be specified. If a modification is matched by both the inclusion and exclusion filter, then the exclusion filter will take preference and the modification will not be included in the modification set. At this point, CCNet only supports three types of filters: PathFilters, UserFilters, and ActionFilters. It is relatively straightforward to build new filters, (such as one to filter modifications based on email address).

Configuration Examples

<sourcecontrol type="filtered">
    <sourceControlProvider type="vss" autoGetSource="true">
      <project>$/Kunigunda/ServiceLocator</project>
      <workingDirectory>C:\CCNet\Kunigunda\ServiceLocator</workingDirectory>
      <username>urosn</username>
      <password></password>
      <ssdir>c:\localvss</ssdir>
    </sourceControlProvider>
    <inclusionFilters>
      <pathFilter>
      	<pattern>$/Kunigunda/ServiceLocator/Sources/**/*.*</pattern>
      </pathFilter>
    </inclusionFilters>
    <exclusionFilters>
    	<pathFilter>
    		<pattern>$/Kunigunda/ServiceLocator/Sources/Kunigunda.ServiceLocator/AssemblyInfo.cs</pattern>
    	</pathFilter>
	<pathFilter>
		<pattern>$/**/*.vssscc</pattern>
	</pathFilter>
	<userFilter>
		<names><name>Perry</name><name>Joe</name></names>
	</userFilter>
	<actionFilter>
		<actions><action>deleted</action></actions>
	</actionFilter>
        <commentFilter>
                <pattern>Ignore: .*</pattern>
        <commentFilter>
    </exclusionFilters>
</sourcecontrol>

This example filters out any modifications to the AssemblyInfo.cs file that have been checked in to Visual Source Safe Source Control Block. Although it shows the use of all four types of filters, you can choose to use only fewer types of filter as well.

Configuration Elements:

FilteredSourceControl root element

This is the root configuration element for the FilteredSourceControl.

Unlike most source control blocks, this one does not support the timeout configuration element

PathFilter element

The PathFilter can be used to filter modifications on the basis of their file path.

UserFilter element

The UserFilter can be used to filter modifications on the basis of the username that committed the changes.

ActionFilter element

The ActionFilter can be used to filter modifications on the basis of the type of modification that was committed. Modification types are specific to each source control provider. Consult each source control provider for the list of actions to filter.

CommentFilter element

The CommentFilter can be used to filter modifications on the basis of the comment that was supplied with the modification.

Comment filters are available starting with build #1.3.0.3052.

Using the PathFilter:

PathFilter supports following wildcards:

Paths do not include the roots Paths do not include the root server identifiers. For example, if you are using subversion source control on server "myserver" and trying to exclude path "svn://myserver/project1/excludedir/*.*" your node should be "/project1/excludedir/*.*".

Path separators are not characters Path separators are not compared as characters, but rather as separations between path elements. The separators "\", "/" and the .Net System.IO.Path.DirectorySeparatorChar are all treated interchangably. This means that the patterns "/Kunigunda/Sources/Test.cs" and "\Kunigunda\Sources\Test.cs" both match the file named "Test.cs" in the folder named "Sources" under the folder named "Kunigunda".

StarTeam needs the full path With StarTeam, use the entire file path as recognized by StarTeam, such as what is displayed when clicking File/Properties/Working File within StarTeam. Examples: c:\project\module1\** c:\project\module2\**\filethatdoesntaffectbuild.txt

Potential enhancements:

1. Case insensitive pattern matching.
2. Current patterns are only an approximation of the patterns used in NAnt filesets. Pattern translation and evaluation types in NAnt assembly are not public so it is not possible to use them directly but it would be a nice optimization.

Implemented and contributed by Uros Novak.
UserFilter and ActionFilter by Perry Ismangil.