About Apache Rat™

Rat audits software distributions, with a special interest in headers. If this isn't quite what you're looking for then take a look at the other products developed by Apache Creadur™, including Apache Whisker™ which audits and generates legal (for example LICENSE) documents for complex software distributions.

Running from the Command Line

Run from the command line with:

java -jar apache-rat/target/apache-rat-0.17-SNAPSHOT.jar --help

This will output a help message detailing the command line options available to you.

Adding license headers

Rat can be used to automatically add license headers to files that do not currently have them. Only files that are not excluded by the Rat configurations will be affected.

To add license headers use a command such as:

java -jar apache-rat/target/apache-rat-0.17-SNAPSHOT.jar --addlicense
  --copyright "Copyright 2008 Foo" --force
  /path/to/project

This command will add the license header directly to the source files. If you prefer to see which files will be changed and how then remove the "--force" option.

Using multiple excludes from a file

It is common to use the Rat with the Maven or Ant plugins and specify a series of files to exclude (such as a README or version control files). If you are using the Rat application instead of a plugin you can specify a series of regex excludes in a file and specify that with the -E option.

java -jar apache-rat/target/apache-rat-0.17-SNAPSHOT.jar
 -E /path/to/project/.rat-excludes
 -d /path/to/project

Command Line Options

usage: java -jar apache-rat/target/apache-rat-0.17-SNAPSHOT.jar [options] [DIR|TARBALL]

====== Available Options ======
 -a                                   (deprecated) Add the default license header to any file with an unknown license.  Use '-A'
                                      or ---addLicense instead.
 -A,--addLicense                      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 --force option.
    --archive <ProcessingType>        Specifies the level of detail in ARCHIVE file reporting. (default is NOTIFICATION)
 -c,--copyright <arg>                 The copyright message to use in the license headers, usually in the form of "Copyright 2008
                                      Foo"
 -d,--dir <DirOrArchive>              (deprecated, use '--') Used to indicate source when using --exclude.
    --dry-run                         If set do not update the files but generate the reports.
 -e,--exclude <Expression>            Excludes files matching wildcard <expression>. May be followed by multiple arguments. Note
                                      that '--' or a following option is required when using this parameter.
 -E,--exclude-file <FileOrURI>        Excludes files matching regular expression in the input file.
 -f,--force                           Forces any changes in files to be written directly to the source files (i.e. new files are
                                      not created).
 -h,--help                            Print help for the RAT command line interface and exit.
    --licenses <FileOrURI>            File names or URLs for license definitions
    --list-families <LicenseFilter>   List the defined license families (default is NONE). Valid options are: ALL, APPROVED, NONE
    --list-licenses <LicenseFilter>   List the defined licenses (default is NONE). Valid options are: ALL, APPROVED, NONE
    --log-level <LogLevel>            sets the log level.
    --no-default-licenses             Ignore default configuration. By default all approved default licenses are used
 -o,--out <arg>                       Define the output file where to write a report to (default is System.out).
 -s,--stylesheet <StyleSheet>         XSLT stylesheet to use when creating the report.  Not compatible with -x.  Either an
                                      external xsl file may be specified or one of the internal named sheets: plain-rat (default),
                                      missing-headers, or unapproved-licenses
    --scan-hidden-directories         Scan hidden directories
    --standard <ProcessingType>       Specifies the level of detail in STANDARD file reporting. (default is ABSENCE)
 -x,--xml                             Output the report in raw XML format.  Not compatible with -s

====== Argument Types ======

<DirOrArchive>
      A directory or archive file to scan

<Expression>
      A wildcard file matching pattern. example: *-test-*.txt

<FileOrURI>
      A file name or URI

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

<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

<StyleSheet>
      Either an external xsl file or maybe 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.

====== Notes ======

1. Rat highlights possible issues.
2. Rat reports require interpretation.
3. Rat often requires some tuning before it runs well against a project.
4. Rat relies on heuristics: it may miss issues

Styling output

Rat allows you to style the output as you see fit. Three stylesheets are included in the rat package.

These stylesheets can be specified using options in the command line, Maven or Ant clients.