This document describes how to run Checkstyle using the command line tool. The latest version of Checkstyle can be found at http://checkstyle.sourceforge.net. This command line tool is included in the Checkstyle distribution.
Checkstyle will process the specified files and by default report errors to standard out in plain format. Checkstyle requires a configuration XML file that configures the checks to apply. Command line options are:
-c configurationFile
- specifies the location of the
file that defines the configuration modules. The location can either
be a filesystem location, or a name passed to the
ClassLoader.getResource() method.
-f format
- specify the output
format. Options are "plain"
for the DefaultLogger
and "xml"
for the XMLLogger.
Defaults to "plain"
.
-p propertiesFile
- specify a
properties file to use.
-o file
- specify the file to output
to.
-t, --tree
- print Abstract Syntax Tree(AST) of the checked file. The option
cannot be used other options and requires exactly one file to run on to be specified.
-T, --treeWithComments
- print Abstract Syntax Tree(AST) with comment nodes of the checked file. The option
cannot be used other options and requires exactly one file to run on to be specified.
-J, --treeWithJavadoc
- print Abstract Syntax Tree(AST) with Javadoc nodes and comment nodes
of the checked file. Attention that line number and columns will not be the same as it is a file due to the fact
that each javadoc comment is parsed separately from java file. The option cannot be used other options and requires
exactly one file to run on to be specified.
-j, --javadocTree
- print Parse Tree of the Javadoc comment.
The file have to contain only Javadoc comment content without including '/**' and '*/' at the beginning and at the end respectively.
For example:
MyTestFile.javadoc
The option
cannot be used other options and requires exactly one file to run on to be specified.
-d, --debug
- Print all debug logging of CheckStyle utility.
-e, --exclude excludedDirectory
- Directory to exclude from
CheckStyle. The directory can be the full, absolute path, or relative to the current path.
Multiple excludes are allowed.
-x, --exclude-regexp excludedDirectoryPattern
- Directory pattern to exclude from
CheckStyle. Multiple excludes are allowed.
-v
- print product version and exit. Any other option is ignored.
Note that the -n packageNamesFile
option has been dropped for Checkstyle 5.0, because of
significant changes regarding package name file handling. See for details.
Set the properties for expanded
property values by either by assigning system properties using the
-D<property>=<value>
arguments to java or
specifying a property file using the -p
option. If a
property file is specified, the system properties are ignored.
It is possible to run Checkstyle directly from the JAR file using
the -jar
option. Download latest
checkstyle-${projectVersion}-all.jar.
An example of run would be:
It is recommended to use configuration files that are embedded in jar files, but latest configuration files are there:
sun_checks.xml
google_checks.xml
To run Checkstyle UI viewer for AST tree directly from the JAR file using
the -jar
option. Download latest
checkstyle-${projectVersion}-all.jar.
An example of run would be (path to java file is optional):
Download and compile: Run validation with arguments: Run UI application for file : Build all jars, and launch CLI from new build:
The easiest way is to include
checkstyle-${projectVersion}-all.jar in the
classpath. Alternatively, you must include the
compile
third party dependencies listed in
Project Dependencies in the
classpath.
Run checkstyle with configuration file at
docs/sun_checks.xml
on a filesystem
Run checkstyle with configuration file
docs/sun_checks.xml
on all Java files in a directory
Run checkstyle with configuration file
docs/sun_checks.xml
on a file and provide a system
property
Run checkstyle with configuration file
docs/sun_checks.xml
on a file and use properties in a
file
Run checkstyle with configuration file
docs/sun_checks.xml
on a file and output to a file in
XML format
Run checkstyle with custom module(s) (Root module, Checks, etc) in configuration file:
Note: Custom modules should be specified with the class' full classpath in the configuration file and the compiled class be located in the custom JAR for Checkstyle to find.