Ant Selectors

Three rules explain every result on this page:

Tasks that process directories as well as files (copy, delete) offer them to the selectors too. Use type when a selector should be restricted to one kind.

Every selector can also be written in a project-level selector element with an id and used later by refid; see Selector references and conditional selection.

Source: Apache Ant manual: Core Selectors

Three groups of these were added after the Ant versions that most printed material describes. Books and articles written for Ant 1.7 or 1.8 do not know executable, symlink and ownedBy (1.10.0), posixGroup and posixPermissions (1.10.4) or windowsjunction (1.10.16), and describe modified and different the way they worked then. The manual of the release you run is the reference.

contains and containsregexp open every candidate file and read it with the JVM default encoding (encoding on contains overrides it since Ant 1.9.0). containsregexp uses the regular expression implementation Ant is configured with, which is java.util.regex unless a regexp implementation is chosen (see Filters & Mappers). With the default flags ^ and $ match only at the start and end of the whole file, so a line-anchored pattern needs multiline="true".

The first selects the four model records, the second selects every file whose package line names the model or the engine, which leaves out the CLI:

The listing comes from a small show macro defined in the build file; it prints the sorted members of a fileset with pathconvert, so only the file lists are real output of the selectors and the macro itself is plumbing.

Source: Apache Ant manual: Contains Selector, Regular Expression Selector

date takes datetime in the format MM/dd/yyyy hh:mm a with the US locale unless pattern supplies another SimpleDateFormat pattern, or an absolute millis. when defaults to equal, which is rarely what a build wants: write before or after. granularity is the leeway in milliseconds for file systems with coarse timestamps and defaults to zero, or two seconds on DOS-like systems.

size counts bytes. With units="k" the multiplier is 1000, with the IEC spelling units="Ki" it is 1024 (M/Mi, G/Gi likewise). depth counts directory levels below the base directory of the fileset: a file directly in the base is at depth 0. filename is the selector form of include and exclude, useful because it can sit inside a container with other selectors; negate="true" turns it into an exclude. type chooses file or dir.

The fixture target had set the modification time of Height.java to the year 2020, so it is the only file date finds. docs/index.txt is one level below the base directory, docs/img/logo.png two, so depth max="1" keeps only the first. Only the CLI Main.java and StationReader.java are larger than 1024 bytes:

Source: Apache Ant manual: Date Selector, Size Selector, Depth Selector, Filename Selector

Three selectors answer "does the other tree already have this?" and are the building blocks of hand-written incremental builds. Each takes a targetdir and an optional nested mapper (the identity mapper when absent) that turns a source name into the name to look for in targetdir. See Filters & Mappers for the mappers.

The fixture target gives Station.class a timestamp in 2020 (older than Station.java), makes Height.class newer than Height.java, and creates no class file for the other two sources. For different it copies the model sources to build/snapshot, appends a line to the snapshot’s Height.java and gives the snapshot’s TideEvent.java a timestamp in the future.

depend skipped Height.java (its class file is newer) and selected the stale Station.java and the two sources without a class file. present="srconly" found only the two sources without a class file. different with its defaults reports only the file whose content changed; with ignoreFileTimes="false" and ignoreContents="true" it also reports TideEvent.java, whose content is identical but whose timestamp is not, and Height.java, whose length is different.

different exists for the cases the other two cannot handle: a predecessor that always rewrites its output (a download, a generator), where a timestamp comparison would always say "newer". Comparing content makes the dependency depend on the absolute state of the files. Setting preservelastmodified="true" on a copy that uses it keeps the timestamps equal so later comparisons stay cheap.

Source: Apache Ant manual: Depend Selector, Present Selector, Different Selector

modified is the only selector with state. For each file it computes a value with an algorithm, reads the value stored for the file’s absolute path in a cache, compares the two with a comparator, updates the cache when they differ and selects the file when they differ. The defaults are the digest algorithm (MD5), the propertyfile cache (a cache.properties file in the project’s base directory, also when Ant is started from another directory with -f) and the equal comparator. The other algorithms are hashvalue (the hashCode of the content as a String), checksum (CRC or ADLER) and lastmodified; custom algorithm, cache and comparator classes are set with algorithmclass, cacheclass and comparatorclass and found through a nested classpath. The rule comparator (java.text.RuleBasedCollator) is documented as unusable: its manual section says you should not use it because of a problem in its initialization.

Attributes can also be given as nested param elements, including the algorithm and cache specific ones such as algorithm.algorithm (MD5, SHA) and cache.cachefile. The cache is written when the first build event after the change arrives (delayupdate defaults to true); set delayupdate="false" to store after every change. update="false" makes the selector read-only. Because the cache is keyed by absolute path, a cache file copied to another checkout selects everything again.

The first pass found no cache, so every file differed and all three were copied. After index.txt was edited, only that file was selected, and the cache now holds the MD5 digests. The classic use is uploading only changed files to a server (ftp, scp) from a generated site. modified can also be a resource selector inside restrict; for a resource that is not a file it first copies the content to a temporary file.

Source: Apache Ant manual: Modified Selector

readable, writable, executable, symlink, ownedBy, posixGroup, posixPermissions and windowsjunction ask the file system through java.io.File or java.nio.file.Files and select the file only when the JVM can tell. If the platform does not support the question (POSIX attributes on Windows, for instance) they select nothing, except readable and writable, which the manual says still select a file when the JVM cannot detect that it is unreadable or unwritable. ownedBy, posixGroup and posixPermissions take followsymlinks (default true).

posixPermissions accepts either the nine-character form (rwxr-xr-x) or octal (755). Note that rw------- and 600 describe exactly one permission set, so a file with rw-r--r-- is not selected by either. A fileset with followsymlinks="false" does not return symbolic links at all, so combining it with symlink selects nothing; leave followsymlinks at its default to find links.

latest.txt is a link to notes.txt. With the default followsymlinks="true" the selector sees the permissions of the target, so a separate run with permissions="644" and no followsymlinks listed both latest.txt and notes.txt. With followsymlinks="false" it looks at the link itself and does not select it, so octal-nofollow lists only notes.txt. windowsjunction (Ant 1.10.16) and signedselector were not run here: the first needs Windows, the second a signed JAR.

Source: Apache Ant manual: Executable Selector, Symlink Selector, PosixPermissions Selector, Windows Junction Selector

A container combines the answers of the selectors nested in it. Containers can nest to any depth.

Because and, or and none stop early, put cheap selectors (filename, depth, size) before expensive ones (contains, containsregexp) so a file is rarely opened.

Height.java is only 118 bytes, so the and excludes it. Only StationReader.java satisfies two of the three majority conditions (it is in the engine and is larger than 1000 bytes). Of the three, TideEngine.java is in the engine but is 916 bytes, and the model records contain record but fail the other two.

Source: Apache Ant manual: Selector Containers

The selector element wraps one selector (which can be a container) and gives it an id, so it can be defined once at project level and reused with <selector refid="..."/> in any fileset. It also takes if and unless, the same property tests as on targets and on include/exclude in a patternset, which makes the choice of files depend on the properties set when Ant starts: -Dwith.cli=true adds the CLI sources below, -Dwithout.engine=true removes the engine.

With neither property set, if="with.cli" is false and unless="without.engine" is true, so only the engine is selected. Only Station.java (231 bytes) passes the size test of the shared selector.

Source: Apache Ant manual: Selector Reference

custom plugs in your own class that implements org.apache.tools.ant.types.selectors.FileSelector, configured through nested param elements. Its attributes are classname (required), classpath and classpathref; with neither classpath the class must be on Ant’s own classpath. A few core selectors can be used through custom with their attributes written as param elements: contains, date, depth, filename and size, plus modified. The depth example below uses it with the core class, which proves the mechanism without compiling anything:

This is the same result as <depth max="1"/> above. Writing the Java class, extending BaseExtendSelector and registering a selector with typedef are covered in Custom Types, Conditions & Selectors.

Source: Apache Ant manual: Custom Selectors, Programming Selectors in Ant

scriptselector runs a script for every candidate file, in any language that Apache BSF or JSR 223 supports. The script sees the bean self (call self.setSelected(true) to select the file), filename, file and basedir, plus the usual project, properties and targets. If src is not set, the script is the element’s text. The Ant manual’s example selects the files with an even-length name:

This was not run successfully here: Ant 1.10.18 on JDK 26 has no JavaScript engine, because Java 15 removed Nashorn, and the build stops with the message below. A script engine such as GraalVM JavaScript (or any other JSR 223 language) must be added to Ant’s classpath first; see Installation for where libraries go and Scripting for the script task, its engines and the security implications.

Source: Apache Ant manual: Script Selector

Ant is the only one of the three tools whose file collections accept arbitrary predicates as elements; Maven and Gradle reduce the question to patterns and, in Gradle, to code.

An Ant selector that has no equivalent is where the usual migration advice applies: in Gradle, the build script is code, so the predicate is a lambda; in Maven, the cleanest route is a small plugin or a profile that changes the pattern lists. The selector-by-selector view is in Migrating Between Tools.