Ant: The Definitive Guide

FileSet DataType

The fileset DataType defines a group of files and is commonly represented by the <fileset> element. However, many Ant tasks form implicit filesets, which means they support all fileset attributes and nested elements. Unlike the filelist type, files represented by fileset must exist. Filesets may also be specified as target-level buildfile elements (i.e., children of <project>) and referenced by their ids. Following is a list of fileset attributes:

dir (all, Path, Y)

The base directory for the fileset.

casesensitive (1.4.1, boolean N)

If set to false, the fileset is not case-sensitive when matching filenames. Defaults to true. Ant versions prior to 1.4.1 use case-sensitive matching.

defaultexcludes (all, boolean, N)

Determines whether to use default excludes. Defaults to true. Default excludes consists of: **/*~, **/#*#, **/.#*, **/%*%, **/CVS, **/CVS/**, **/.cvsignore, **/SCCS, **/SCCS/**, and **/vssver.scc.

excludes (all, String, N)

A comma-separated list of file patterns to exclude. These are in addition to the default excludes.

excludesfile (all, File, N)

The name of a file containing one exclude pattern per line. These are in addition to the default excludes.

includes (all, String, N)

A comma-separated list of file patterns to include.

includesfile (all, File, N)

The name of a file containing one include pattern per line.

In addition to the attributes listed, a fileset may also contain the following:

0..n nested patternset elements: <exclude>, <include>, <patternset> (all); <excludesfile>, <includesfile>. (1.4)

These define which files are included and/or excluded from the fileset. All are described shortly in Section 4.7. Other than <patternset>, these nested elements are used in place of their corresponding attributes.

Examples

The following examples produce identical results. Since fileset depends heavily on patternset, you should continue on and read the “Patternset DataType” section after studying these examples. The first example uses includes and excludes attributes to select all .java files in the src directory, excluding any such files underneath any directories named test:

<fileset id="sources1" dir="src"
          includes="**/*.java"
               
          excludes="**/test/**/*.java">
</fileset>

The next example uses nested <include> and <exclude> tags in place of the includes and excludes attributes:

<fileset id="sources2" dir="src">
  <include name="**/*.java"/>
               
  <exclude name="**/test/**/*.java"/>
</fileset>

By using the nested <include> or <exclude> element, you gain the ability to selectively include or exclude files based on properties. For instance, you can selectively include using the following syntax, which is described shortly under “PatternSet DataType”:

<!-- Skip unit tests unless the includeTests property is set -->
<exclude name="**/test/**/*.java" unless="includeTests"/>

You may also use a nested <patternset> element to achieve the same results:

<fileset id="sources3" dir="src">
  <patternset>
               
    <include name="**/*.java"/>
               
    <exclude name="**/test/**/*.java"/>
               
  </patternset>
</fileset>

And finally, we define a <patternset> in one place and refer to it in two other places. This is more useful than the previous example, because it allows you to reuse a common patternset throughout a buildfile:

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

<!-- later in the same buildfile -->
<fileset id="sources4" dir="src">
  <patternset refid="non.test.source"/>
</fileset>
<fileset id="sources5" dir="othersrc">
  <patternset refid="non.test.source"/>
</fileset>

Include and Exclude Pattern Syntax

Ant uses patterns to include and exclude files. For instance, **/*.java matches all .java files in any subdirectory. The syntax is straightforward:

* matches zero or more characters. *.java matches Account.java and Person.java, but not settings.properties.

? matches one character. File?.java matches FileA.java and FileB.java, but not FileTest.java.

** matches zero or more directories. /xml/** matches all files and directories under /xml/.

Combinations of patterns are allowed. For instance, a more sophisticated pattern, com/oreilly/**/*Test.java, matches any of these files:

com/oreilly/antbook/AccountTest.java

com/oreilly/antbook/util/UnitTest.java

com/oreilly/AllTest.java