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 --exclude-file option.

java -jar apache-rat/target/apache-rat-0.17-SNAPSHOT.jar
 --exclude-file /path/to/project/.rat-excludes
  /path/to/project

Command Line Options

INFO: Apache Creadur RAT 0.17-SNAPSHOT (Apache Software Foundation)
usage: java -jar apache-rat/target/apache-rat-0.17-SNAPSHOT.jar [options] [DIR|ARCHIVE]

====== Available Options ======
 -?,--help                                            Print help for the RAT command line interface and exit.
 -a                                                   [Deprecated for removal since 0.17: Use --edit-license instead.]
 -A,--addLicense                                      [Deprecated for removal since 0.17: Use --edit-license instead.]
                                                      Add the default license header to any file with an unknown license
                                                      that is not in the exclusion list.
 -c,--copyright <arg>                                 [Deprecated for removal since 0.17: Use --edit-copyright instead.]
                                                      The copyright message to use in the license headers.
    --config <File>                                   File names for system configuration. Multiple values may be
                                                      specified. Note that '--' or a following option is required when
                                                      using this parameter.
    --configuration-no-defaults                       Ignore default configuration.
    --counter-max <CounterPattern>                    The acceptable maximum number for the specified counter. A value
                                                      of '-1' specifies an unlimited number. Multiple values may be
                                                      specified. Note that '--' or a following option is required when
                                                      using this parameter.
    --counter-min <CounterPattern>                    The minimum number for the specified counter. Multiple values may
                                                      be specified. Note that '--' or a following option is required
                                                      when using this parameter.
 -d,--dir <DirOrArchive>                              [Deprecated for removal since 0.17: Use the standard '--' to
                                                      signal the end of arguments.] Used to indicate end of list when
                                                      using options that take multiple arguments.
    --dry-run                                         If set do not update the files but generate the reports.
 -e,--exclude <Expression>                            [Deprecated for removal since 0.17: Use --input-exclude instead.]
                                                      Excludes files matching <Expression>. Multiple values may be
                                                      specified. Note that '--' or a following option is required when
                                                      using this parameter.
 -E,--exclude-file <File>                             [Deprecated for removal since 0.17: Use --input-exclude-file
                                                      instead.] Reads <Expression> entries from a file. Entries will be
                                                      excluded from processing.
    --edit-copyright <arg>                            The copyright message to use in the license headers. Usually in
                                                      the form of "Copyright 2008 Foo".  Only valid with --edit-license
    --edit-license                                    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 --edit-overwrite option.
    --edit-overwrite                                  Forces any changes in files to be written directly to the source
                                                      files (i.e. new files are not created). Only valid with
                                                      --edit-license
 -f,--force                                           [Deprecated for removal since 0.17: Use --edit-overwrite instead.]
                                                      Forces any changes in files to be written directly to the source
                                                      files (i.e. new files are not created).
    --help-licenses                                   Print information about registered licenses.
    --include <Expression>                            [Deprecated for removal since 0.17: Use --input-include instead.]
                                                      Includes files matching <Expression>. Will override excluded
                                                      files. Multiple values may be specified. Note that '--' or a
                                                      following option is required when using this parameter.
    --includes-file <File>                            [Deprecated for removal since 0.17: Use --input-include-file
                                                      instead.] Reads <Expression> entries from a file. Entries will be
                                                      excluded from processing.
    --input-exclude <Expression>                      Excludes files matching <Expression>. Multiple values may be
                                                      specified. Note that '--' or a following option is required when
                                                      using this parameter.
    --input-exclude-file <File>                       Reads <Expression> entries from a file. Entries will be excluded
                                                      from processing.
    --input-exclude-parsed-scm <StandardCollection>   Parse SCM based exclusion files to exclude specified files and
                                                      directories. Multiple values may be specified. Note that '--' or a
                                                      following option is required when using this parameter.
    --input-exclude-size <Integer>                    Excludes files with sizes less than the given argument.
    --input-exclude-std <StandardCollection>          Excludes files defined in standard collections based on commonly
                                                      occurring groups. Multiple values may be specified. Note that '--'
                                                      or a following option is required when using this parameter.
    --input-include <Expression>                      Includes files matching <Expression>. Will override excluded
                                                      files. Multiple values may be specified. Note that '--' or a
                                                      following option is required when using this parameter.
    --input-include-file <File>                       Reads <Expression> entries from a file. Entries will override
                                                      excluded files.
    --input-include-std <StandardCollection>          Includes files defined in standard collections based on commonly
                                                      occurring groups. Will override excluded files. Multiple values
                                                      may be specified. Note that '--' or a following option is required
                                                      when using this parameter.
    --input-source <File>                             A file containing file names to process. File names must use linux
                                                      directory separator ('/') or none at all. File names that do not
                                                      start with '/' are relative to the directory where the argument is
                                                      located. Multiple values may be specified. Note that '--' or a
                                                      following option is required when using this parameter.
    --license-families-approved <FamilyID>            The approved License Family IDs. These licenses families will be
                                                      added to the list of approved licenses families. Multiple values
                                                      may be specified. Note that '--' or a following option is required
                                                      when using this parameter.
    --license-families-approved-file <File>           Name of file containing the approved family IDs.
    --license-families-denied <FamilyID>              The denied License family IDs. These license families will be
                                                      removed from the list of approved licenses. Multiple values may be
                                                      specified. Note that '--' or a following option is required when
                                                      using this parameter.
    --license-families-denied-file <File>             Name of file containing the denied license IDs.
    --licenses <File>                                 [Deprecated for removal since 0.17: Use --config instead.] File
                                                      names for system configuration. Multiple values may be specified.
                                                      Note that '--' or a following option is required when using this
                                                      parameter.
    --licenses-approved <LicenseID>                   The approved License IDs. These licenses will be added to the list
                                                      of approved licenses. Multiple values may be specified. Note that
                                                      '--' or a following option is required when using this parameter.
    --licenses-approved-file <File>                   Name of file containing the approved License IDs.
    --licenses-denied <LicenseID>                     The denied License IDs. These licenses will be removed from the
                                                      list of approved licenses. Once licenses are removed they can not
                                                      be added back. Multiple values may be specified. Note that '--' or
                                                      a following option is required when using this parameter.
    --licenses-denied-file <File>                     Name of file containing the denied license IDs.
    --list-families <LicenseFilter>                   [Deprecated for removal since 0.17: Use --output-families
                                                      instead.] List the defined license families. (Default value =
                                                      NONE)
    --list-licenses <LicenseFilter>                   [Deprecated for removal since 0.17: Use --output-licenses
                                                      instead.] List the defined licenses. (Default value = NONE)
    --log-level <LogLevel>                            Sets the log level. (Default value = WARN)
    --no-default-licenses                             [Deprecated for removal since 0.17: Use
                                                      --configuration-no-defaults instead.] Ignore default
                                                      configuration.
 -o,--out <File>                                      [Deprecated for removal since 0.17: Use --output-file instead.]
                                                      Define the output file where to write a report to. (Default value
                                                      = System.out)
    --output-archive <ProcessingType>                 Specifies the level of detail in ARCHIVE file reporting. (Default
                                                      value = NOTIFICATION)
    --output-families <LicenseFilter>                 List the defined license families. (Default value = NONE)
    --output-file <File>                              Define the output file where to write a report to. (Default value
                                                      = System.out)
    --output-licenses <LicenseFilter>                 List the defined licenses. (Default value = NONE)
    --output-standard <ProcessingType>                Specifies the level of detail in STANDARD file reporting. (Default
                                                      value = ABSENCE)
    --output-style <StyleSheet>                       XSLT stylesheet to use when creating the report. Either an
                                                      external xsl file may be specified or one of the internal named
                                                      sheets.
 -s,--stylesheet <StyleSheet>                         [Deprecated for removal since 0.17: Use --output-style instead.]
                                                      XSLT stylesheet to use when creating the report.
    --scan-hidden-directories                         [Deprecated for removal since 0.17: Use --input-include-std with
                                                      'HIDDEN_DIR' argument instead.] Scans hidden directories.
 -x,--xml                                             [Deprecated for removal since 0.17: Use --output-style with the
                                                      'xml' argument instead.] forces XML output rather than the textual
                                                      report.

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

<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.

====== Standard Collections ======


<ALL>
     All of the Standard Excludes combined.
     File patterns: **/MANIFEST.MF, **/ChangeSet/**, **/TAGS/**, **/*.old, **/pom.xml.releaseBackup, **/*.ipr,
         **/.del-*, **/*$, **/.settings/**, **/BitKeeper/**, **/CVS.adm/**, **/*.so, **/.classpath, **/*.rej,
         **/.bzr/**, **/*.elc, **/._*, **/*~, **/*.iml, **/build.log, **/.mvn/**, **/.svn/**, **/.hgignore,
         **/project.pj, **/-darcs-backup*, **/*.ln, **/.metadata/**, **/.project, **/cvslog.*, **/.make.state,
         **/.factorypath, **/core, **/CVS/**, **/.idea/**, **/.git/**, **/%*%, **/.checkstyle, **/_$*, **/.hg/**,
         **/*.BAK, **/.arch-ids/**, **/.bzrignore, **/*.o, **/release.properties, **/SCCS/**, **/,*, **/*.Z, **/.#*,
         **/vssver.scc, **/#*#, **/*.a, **/*.iws, **/target/**, **/RCS/**, **/*.bak, **/.externalToolBuilders,
         **/*.orig, **/.darcs-temp-mail, **/.nse_depinfo, **/RCSLOG/**, **/*.exe, **/tags/**, **/.gitignore,
         **/.MySCMServerInfo, **/#*, **/*.obj, **/_darcs/**, **/.repository, **/cobertura.ser, **/.darcsrepo/**,
         **/.DS_Store, **/.cvsignore
     Provides a path matcher: true
     Provides a file processor: true

<ARCH>
     The files and directories created by an ARCH source code control based tool.
     File patterns: **/.arch-ids/**
     Provides a path matcher: false
     Provides a file processor: false

<BAZAAR>
     The files and directories created by a Bazaar source code control based tool.
     File patterns: **/.bzr/**, **/.bzrignore
     Provides a path matcher: false
     Provides a file processor: true

<BITKEEPER>
     The files and directories created by a Bitkeeper source code control based tool.
     File patterns: **/BitKeeper/**, **/ChangeSet/**
     Provides a path matcher: false
     Provides a file processor: false

<CVS>
     The files and directories created by a CVS source code control based tool.
     File patterns: **/TAGS/**, **/_$*, **/*.old, **/*.BAK, **/.del-*, **/*$, **/*.o, **/SCCS/**, **/,*, **/CVS.adm/**,
         **/*.so, **/*.rej, **/*.Z, **/.#*, **/*.elc, **/*.a, **/*~, **/RCS/**, **/*.bak, **/*.orig, **/.nse_depinfo,
         **/RCSLOG/**, **/*.exe, **/*.ln, **/tags/**, **/#*, **/*.obj, **/cvslog.*, **/.make.state, **/core, **/CVS/**,
         **/.cvsignore
     Provides a path matcher: false
     Provides a file processor: true

<DARCS>
     The files and directories created by a DARCS source code control based tool.
     File patterns: **/_darcs/**, **/.darcsrepo/**, **/-darcs-backup*, **/.darcs-temp-mail
     Provides a path matcher: false
     Provides a file processor: false

<ECLIPSE>
     The files and directories created by an Eclipse IDE based tool.
     File patterns: **/.project, **/.checkstyle, **/.classpath, **/.factorypath, **/.externalToolBuilders,
         **/.settings/**
     Provides a path matcher: false
     Provides a file processor: false

<GIT>
     The files and directories created by GIT source code control to support GIT, also processes files listed in
         '.gitignore'.
     File patterns: **/.git/**, **/.gitignore
     Provides a path matcher: false
     Provides a file processor: true

<HIDDEN_DIR>
     The hidden directories. Directories with names that start with '.'
     File patterns: <none>
     Provides a path matcher: true
     Provides a file processor: false

<HIDDEN_FILE>
     The hidden files. Directories with names that start with '.'
     File patterns: <none>
     Provides a path matcher: true
     Provides a file processor: false

<IDEA>
     The files and directories created by an IDEA IDE based tool.
     File patterns: **/*.iws, **/*.iml, **/*.ipr, **/.idea/**
     Provides a path matcher: false
     Provides a file processor: false

<MAC>
     The .DS_Store files on Mac computers.
     File patterns: **/.DS_Store
     Provides a path matcher: false
     Provides a file processor: false

<MAVEN>
     The files and directories created by Maven build system based project.
     File patterns: **/MANIFEST.MF, **/pom.xml.releaseBackup, **/build.log, **/target/**, **/.repository, **/.mvn/**,
         **/cobertura.ser, **/release.properties
     Provides a path matcher: false
     Provides a file processor: false

<MERCURIAL>
     The files and directories created by a Mercurial source code control based tool.
     File patterns: **/.hg/**, **/.hgignore
     Provides a path matcher: false
     Provides a file processor: true

<MISC>
     The set of miscellaneous files generally left by editors and the like.
     File patterns: **/*~, **/%*%, **/.#*, **/._*, **/#*#
     Provides a path matcher: false
     Provides a file processor: false

<MKS>
     The files and directories created by an MKS source code control based tool.
     File patterns: **/project.pj
     Provides a path matcher: false
     Provides a file processor: false

<RCS>
     The files and directories created by a RCS source code control based tool.
     File patterns: **/RCS/**
     Provides a path matcher: false
     Provides a file processor: false

<SCCS>
     The files and directories created by a SCCS source code control based tool.
     File patterns: **/SCCS/**
     Provides a path matcher: false
     Provides a file processor: false

<SERENA_DIMENSIONS_10>
     The files and directories created by a Serena Dimensions V10 change control system based tool.
     File patterns: **/.metadata/**
     Provides a path matcher: false
     Provides a file processor: false

<STANDARD_PATTERNS>
     A standard collection of generally accepted patterns to ignore.
     File patterns: **/ChangeSet/**, **/TAGS/**, **/*.old, **/.del-*, **/*$, **/BitKeeper/**, **/CVS.adm/**, **/*.so,
         **/*.rej, **/.bzr/**, **/*.elc, **/._*, **/*~, **/.svn/**, **/.hgignore, **/project.pj, **/-darcs-backup*,
         **/*.ln, **/.metadata/**, **/cvslog.*, **/.make.state, **/core, **/CVS/**, **/.git/**, **/%*%, **/_$*,
         **/.hg/**, **/*.BAK, **/.arch-ids/**, **/.bzrignore, **/*.o, **/SCCS/**, **/,*, **/*.Z, **/.#*, **/vssver.scc,
         **/#*#, **/*.a, **/RCS/**, **/*.bak, **/*.orig, **/.darcs-temp-mail, **/.nse_depinfo, **/RCSLOG/**, **/*.exe,
         **/tags/**, **/.gitignore, **/.MySCMServerInfo, **/#*, **/*.obj, **/_darcs/**, **/.darcsrepo/**, **/.DS_Store,
         **/.cvsignore
     Provides a path matcher: false
     Provides a file processor: true

<STANDARD_SCMS>
     A standard collection of SCMs
     File patterns: **/.git/**, **/TAGS/**, **/_$*, **/*.old, **/*.BAK, **/.del-*, **/.hg/**, **/*$, **/.bzrignore,
         **/*.o, **/SCCS/**, **/,*, **/CVS.adm/**, **/*.so, **/*.rej, **/*.Z, **/.#*, **/.bzr/**, **/*.elc, **/*.a,
         **/*~, **/.svn/**, **/RCS/**, **/*.bak, **/.hgignore, **/*.orig, **/.nse_depinfo, **/RCSLOG/**, **/*.exe,
         **/*.ln, **/tags/**, **/.gitignore, **/#*, **/*.obj, **/cvslog.*, **/.make.state, **/core, **/CVS/**,
         **/.cvsignore
     Provides a path matcher: false
     Provides a file processor: true

<SUBVERSION>
     The files and directories created by a Subversion source code control based tool.
     File patterns: **/.svn/**
     Provides a path matcher: false
     Provides a file processor: false

<SURROUND_SCM>
     The files and directories created by a Surround SCM source code control based tool.
     File patterns: **/.MySCMServerInfo
     Provides a path matcher: false
     Provides a file processor: false

<VSS>
     The files and directories created by a Visual Source Safe source code control based tool.
     File patterns: **/vssver.scc
     Provides a path matcher: false
     Provides a file processor: false

A path matcher will match specific information about the file.

A file processor will process the associated "ignore" file for include and exclude directives

====== 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