PatternSet Type

## PatternSet

Patterns can be grouped to sets and later be referenced by their id attribute. They are defined via a `patternset` element, which can appear nested into a FileSet or a directory-based task that constitutes an implicit FileSet. In addition, `patternset`s can be defined as a stand alone element at the same level as `target`—i.e., as children of `project` as well as as children of `target`.

Patterns can be specified by nested `<include>`, or `<exclude>` elements or the following attributes.

Attribute | Description | Default
--- | --- | ---
includes | comma- or space-separated list of patterns of files that must be included. | All files are included.
includesfile | name of a file; each line of this file is taken to be an include pattern. You can specify more than one include file by using a nested `includesfile` elements. Note: if the file is empty and there are no other patterns defined for the fileset, all files will be included. | See includes
excludes | comma- or space-separated list of patterns of files that must be excluded. | No files except default excludes are excluded.
excludesfile | name of a file; each line of this file is taken to be an exclude pattern. You can specify more than one exclude file by using a nested `excludesfile` elements. | See excludes
refid | Makes this `patternset` a reference to a `patternset` defined elsewhere. If specified no other attributes or nested elements are allowed. | No

### Parameters specified as nested elements

#### `include` and `exclude`

Each such element defines a single pattern for files to include or exclude.

Attribute | Description | Required
--- | --- | ---
name | the pattern to in/exclude. | Yes
if | Only use this pattern if the named property is set. | No
unless | Only use this pattern if the named property is not set. | No

#### `includesfile` and `excludesfile`

If you want to list the files to include or exclude external to your build file, you should use the includesfile/excludesfile attributes or elements. Using the attribute, you can only specify a single file of each type, while the nested elements can be specified more than once—the nested elements also support if/unless attributes you can use to test the existence of a property.

Attribute | Description | Required
--- | --- | ---
name | the name of the file holding the patterns to in/exclude. | Yes
if | Only read this file if the named property is set. | No
unless | Only read this file if the named property is not set. | No
encoding | The encoding of the file. Since Ant 1.10.4 | No, default is platform default

#### `patternset`

Patternsets may be nested within one another, adding the nested patterns to the parent patternset.

#### `invert`

Since Apache Ant 1.7.1

A nested patternset can be inverted using the `<invert>` element.

### Examples

    <patternset id="non.test.sources">
      <include name="**/*.java"/>
      <exclude name="**/*Test*"/>
    </patternset>

Builds a set of patterns that matches all `.java` files that do not contain the text `Test` in their name. This set can be referred to via `<patternset refid="non.test.sources"/>`, by tasks that support this feature, or by FileSets.

Note that while the includes and excludes attributes accept multiple elements separated by commas or spaces, the nested `<include>` and `<exclude>` elements expect their name attribute to hold a single pattern.

The nested elements allow you to use if and unless attributes to specify that the element should only be used if a property is set, or that it should be used only if a property is not set.

For example

    <patternset id="sources">
      <include name="std/**/*.java"/>
      <include name="prof/**/*.java" if="professional"/>
      <exclude name="**/*Test*"/>
    </patternset>

will only include the files in the sub-directory `prof` if the property `professional` is set to some value.

The two sets

    <patternset includesfile="some-file"/>

and

    <patternset>
      <includesfile name="some-file"/>
    <patternset/>

are identical. The include patterns will be read from the file `some-file`, one pattern per line.

    <patternset>
      <includesfile name="some-file"/>
      <includesfile name="${some-other-file}"
                    if="some-other-file"/>
    <patternset/>

will also read include patterns from the file the property `some-other-file` points to, if a property of that name has been defined.