Report Task

The Report task is the heart of the Apache Rat Ant Task Library, it runs Rat on a given set of resources and generates the report.

The task can work on any Ant resource or resource collection and the usual Ant selectors can be applied to restrict things even further.

Reports can use Rat's internal XML or plain text format or be styled by a custom XSLT stylesheet.

It is possible to define custom matchers for licenses not directly supported by Rat via nested elements to the Report task.

Report Task Attributes

Current

The attribute value types are listed in a table at the bottom of this page.
Name Description Value Type Required
editCopyright The copyright message to use in the license headers. Usually in the form of "Copyright 2008 Foo". Only valid with editLicense attribute Arg false
editOverwrite Forces any changes in files to be written directly to the source files so that new files are not created. Only valid with editLicense attribute. boolean false
editLicense Add the default license header to any file with an unknown license that is not in the exclusion list. By default new files will be created with the license header, to force the modification of existing files use the editOverwrite attribute option. boolean false
configurationNoDefaults Ignore default configuration. boolean false
inputExcludeSize Excludes files with sizes less than the given argument. Integer false
outputStyle XSLT stylesheet to use when creating the report. Either an external xsl file may be specified or one of the internal named sheets. StyleSheet false
outputLicenses List the defined licenses. LicenseFilter false
outputFamilies List the defined license families. LicenseFilter false
dryRun If set do not update the files but generate the reports. boolean false
outputFile Define the output file where to write a report to. File false
outputArchive Specifies the level of detail in ARCHIVE file reporting. ProcessingType false
outputStandard Specifies the level of detail in STANDARD file reporting. ProcessingType false
helpLicenses Print information about registered licenses. boolean false

Deprecated

The attribute value types are listed in a table at the bottom of this page.
Name Description Argument Type Deprecated
copyright The copyright message to use in the license headers. Arg Deprecated for removal since 0.17: Use editCopyright attribute instead.
force Forces any changes in files to be written directly to the source files so that new files are not created. boolean Deprecated for removal since 0.17: Use editOverwrite attribute instead.
addLicense Add the default license header to any file with an unknown license that is not in the exclusion list. boolean Deprecated for removal since 0.17: Use editLicense attribute instead.
noDefaultLicenses Ignore default configuration. boolean Deprecated for removal since 0.17: Use configurationNoDefaults attribute instead.
excludeFile Reads Expression entries from a file. Entries will be excluded from processing. File Deprecated for removal since 0.17: Use inputExcludeFile attribute instead.
includesFile Reads Expression entries from a file. Entries will be excluded from processing. File Deprecated for removal since 0.17: Use inputIncludeFile attribute instead.
scanHiddenDirectories Scans hidden directories. boolean Deprecated for removal since 0.17: Use inputIncludeStd with 'HIDDEN_DIR' argument instead.
stylesheet XSLT stylesheet to use when creating the report. StyleSheet Deprecated for removal since 0.17: Use outputStyle attribute instead.
xml forces XML output rather than the textual report. boolean Deprecated for removal since 0.17: Use outputStyle attribute with the 'xml' argument instead.
listLicenses List the defined licenses. LicenseFilter Deprecated for removal since 0.17: Use outputLicenses attribute instead.
listFamilies List the defined license families. LicenseFilter Deprecated for removal since 0.17: Use outputFamilies attribute instead.
out Define the output file where to write a report to. File Deprecated for removal since 0.17: Use outputFile attribute instead.

Report Task Nested Elements

Current

The element value types are listed in a table at the bottom of this page.
Name Description Value Type Required
config File names for system configuration. File false
licensesApproved A comma separated list of approved License IDs. These licenses will be added to the list of approved licenses. LicenseID false
licenseFamiliesApproved A comma separated list of approved license family IDs. These license families will be added to the list of approved license families. FamilyID false
licensesDenied A comma separated list of denied License IDs. These licenses will be removed from the list of approved licenses. Once licenses are removed they can not be added back. LicenseID false
licenseFamiliesDenied A comma separated list of denied License family IDs. These license families will be removed from the list of approved licenses. Once license families are removed they can not be added back. FamilyID false
counterMax The acceptable maximum number for the specified counter. A value of '-1' specifies an unlimited number. CounterPattern false
counterMin The minimum number for the specified counter. CounterPattern false
inputExclude Excludes files matching Expression. Expression false
inputInclude Includes files matching Expression. Will override excluded files. Expression false
inputExcludeParsedScm Parse SCM based exclusion files to exclude specified files and directories. StandardCollection false

Deprecated

The element value types are listed in a table at the bottom of this page.
Name Description Argument Type Deprecated
licenses File names for system configuration. File Deprecated for removal since 0.17: Use config instead.
exclude Excludes files matching Expression. Expression Deprecated for removal since 0.17: Use inputExclude instead.
include Includes files matching Expression. Will override excluded files. Expression Deprecated for removal since 0.17: Use inputInclude instead.

Argument Types

Arg A string

CounterPattern A pattern comprising one of the following prefixes followed by a colon and a count (e.g. UNAPPROVED:5). Prefixes are

APPROVED: A count of approved licenses. Default range [0, unlimited]

ARCHIVES: A count of archive files. Default range [0, unlimited]

BINARIES: A count of binary files. Default range [0, unlimited]

DOCUMENT_TYPES: A count of distinct document types. Default range [1, unlimited]

IGNORED: A count of ignored files. Default range [0, unlimited]

LICENSE_CATEGORIES: A count of distinct license categories. Default range [1, unlimited]

LICENSE_NAMES: A count of distinct license names. Default range [1, unlimited]

NOTICES: A count of notice files. Default range [0, unlimited]

STANDARDS: A count of standard files. Default range [1, unlimited]

UNAPPROVED: A count of unapproved licenses. Default range [0, 0]

UNKNOWN: A count of unknown file types. Default range [0, unlimited].

DirOrArchive A directory or archive file to scan.

Expression A file matching pattern usually of the form used in Ant build files and '.gitignore' files (see https://ant.apache.org/manual/dirtasks.html#patterns for examples). Regular expression patterns may be specified by surrounding the pattern with '%regex[' and ']'. For example '%regex[[A-Z].*]' would match files and directories that start with uppercase latin letters.

FamilyID The ID for a license family.

File A file name.

Integer An integer value.

LicenseFilter A defined filter for the licenses to include. Valid values: ALL, APPROVED, NONE.

LicenseID The ID for a license.

LogLevel The log level to use. Valid values DEBUG, INFO, WARN, ERROR, OFF.

ProcessingType Specifies how to process file types. Valid values are: NOTIFICATION: List file as present

PRESENCE: List any licenses found

ABSENCE: List licenses found and any unknown licences

StandardCollection Defines standard expression patterns (see above). Valid values are: ALL: All of the Standard Excludes combined.

ARCH: The files and directories created by an ARCH source code control based tool.

BAZAAR: The files and directories created by a Bazaar source code control based tool.

BITKEEPER: The files and directories created by a Bitkeeper source code control based tool.

CVS: The files and directories created by a CVS source code control based tool.

DARCS: The files and directories created by a DARCS source code control based tool.

ECLIPSE: The files and directories created by an Eclipse IDE based tool.

GIT: The files and directories created by GIT source code control to support GIT, also processes files listed in '.gitignore'.

HIDDEN_DIR: The hidden directories. Directories with names that start with '.'

HIDDEN_FILE: The hidden files. Directories with names that start with '.'

IDEA: The files and directories created by an IDEA IDE based tool.

MAC: The .DS_Store files on Mac computers.

MAVEN: The files and directories created by Maven build system based project.

MERCURIAL: The files and directories created by a Mercurial source code control based tool.

MISC: The set of miscellaneous files generally left by editors and the like.

MKS: The files and directories created by an MKS source code control based tool.

RCS: The files and directories created by a RCS source code control based tool.

SCCS: The files and directories created by a SCCS source code control based tool.

SERENA_DIMENSIONS_10: The files and directories created by a Serena Dimensions V10 change control system based tool.

STANDARD_PATTERNS: A standard collection of generally accepted patterns to ignore.

STANDARD_SCMS: A standard collection of SCMs

SUBVERSION: The files and directories created by a Subversion source code control based tool.

SURROUND_SCM: The files and directories created by a Surround SCM source code control based tool.

VSS: The files and directories created by a Visual Source Safe source code control based tool.

StyleSheet Either an external xsl file or one of the internal named sheets. Internal sheets are: plain-rat: The default style.

missing-headers: Produces a report of files that are missing headers.

unapproved-licenses: Produces a report of the files with unapproved licenses.

xml: Produces output in pretty-printed XML.

Examples

The files to be checked by Rat are specified as nested resource (collection)(s), the most basic one would probably be a fileset.

For example the following would check all Java files in the src directory.

<rat:report>
    <fileset dir="src" includes="**/*.java"/>
</rat:report>