Filters

Filters provide a way to watch for changes to specific files, or folders in a path being watched. To add filters to a watch, you would add the <filters> child element, and then one or more filter-type elements within the <filters> element. Filters can be file names, folder names, file or folder attributes and paths relative to the watch path.

Filters are processed before any other function for the watch is performed, so adding a filter will limit notifications, actions, or commands to being run only if a file or folder is matched with a filter.

Structure

<watches>
    <watch>
        <filters>
            <files>
                <name></name>
            </files>
            <folders>
                <name></name>
            </folders>
            <attributes>
                <attribute></attribute>
            </attributes>
            <paths>
                <path></path>
            </paths>
            <log></log>
        </filters>
    </watch>
</watches>

Types of Filters

There are different types of filters that can be specified within the <filters> element. These include the following:

Exclusion	Description
files	File patterns for the filter. For more information, see Patterns.
folders	Folder patterns for the filter. For more information, see Patterns.
attributes	File or folder attributes to match.
paths	Paths relative to the watch path to match.
log	Set to false to disable logging of exclusions, or true to keep logging. Defaults to true.

Each of the above filters represent a child element of the <filters> element for a watch. All of the elements can contain a list of what to filter, so for example, multiple files names can be specified under the <files> element, or multiple attributes can be specified under the <attributes> element.

Any number of filters can be used, so you can filter based on both file names and attributes, or attributes and paths, or even specify filters for each outlined above. When specifying multiple filters, the change is checked against any of the filters, and if it matches the change is included. The change location doesn't have to match all specified filters, it only needs to match one.

The next few sections provide more detail on each of the filters.

Files

The files filters uses the <files> element and contains a list of file naming patterns specified with a <name> child element. Any file names that match those patterns, regardless of their path, will be included in performing any function when changed.

Folders

Folders can be included by specifying each folder pattern under the <folders> element. Much like the files filters, the <name> child element is used to specify a pattern for the folder name. Any path that includes the folder name will be included, so a child folder will be included if a parent folder is in the folder filter list.

Attributes

To filter a file or folder based on its attributes, the <attributes> element can be used. This element will contain a list of one or more <attribute> child elements that specify an attribute to include. The attribute values include the following:

Attribute	Description
Archive	The file or folder is marked as archive.
Compressed	The file or folder is compressed.
Encrypted	The file or folder is encrypted.
Hidden	The file or folder is hidden.
ReadOnly	The file or folder is read only.
System	The file or folder is marked as system.

Note: The above attributes are case-sensitive, so they will need to be added to the configuration file as shown above.

Paths

If a specific file or folder needs to be included, and the file or folder inclusion lists are too broad, you can specify a relative path to the file or folder using the <paths> element. You can specify multiple <path> child elements - one for each path - that you would to include.

By relative path, this means that the path must be specified with the path of the watch removed from the beginning. For example, if the watch path is C:\Temp and you would like to exclude the folder C:\Temp\Docs\Recipe, you would specify the path as Docs\Recipe in the <path> child element. The same would apply to a specific file.

Logging

If a file or folder change was filtered for a specified reason, the inclusion will be logged into the log file. If you are unsure why a function was performed on a change when it shouldn't have been performed, then you can check the log file.

For more information, see Logging.

Examples

Include a file named doc1.doc:

<watches>
    <watch>
        <path>C:\Temp</path>
        <filters>
            <files>
                <name>doc1.doc</name>
            </files>
        </filters>
    <watch>
</watches>

Include a folder named Documents:

<watches>
    <watch>
        <path>C:\Temp</path>
        <filters>
            <folders>
                <name>Documents</name>
            </folders>
        </filters>
    <watch>
</watches>

Include a file or folder with the System attribute:

<watches>
    <watch>
        <path>C:\Temp</path>
        <filters>
            <attributes>
                <attribute>System</attribute>
            </attributes>
        </filters>
    <watch>
</watches>

Include the all .doc files in C:\Temp\ using a file mask:

<watches>
    <watch>
        <path>C:\Temp</path>
        <filters>
            <files>
                <name>*.doc</name>
            </files>
        </filters>
    <watch>
</watches>

Include files named doc1.doc or folders named Documents:

<watches>
    <watch>
        <path>C:\Temp</path>
        <filters>
            <files>
                <name>doc1.doc</name>
            </files>
            <folders>
                <name>Documents</name>
            </folders>
        </filters>
    <watch>
</watches>

Include folders named beginning with T and ending with ing using a regular expression.

<watches>
    <watch>
        <path>C:\Temp</path>
        <filters>
            <folders>
                <name>T.*ing$</name>
            </folders>
        </filters>
    <watch>
</watches>