This document describes how to run Checkstyle using the command line tool. The latest version of Checkstyle can be downloaded as described at Download section. This command line tool is included in the Checkstyle distribution.
java -D<property>=<value> \
com.puppycrawl.tools.checkstyle.Main \
-c <configurationFile> \
[-f <format>] [-p <propertiesFile>] [-o <file>] \
[-s <line:column>] [-g | --generate-xpath-suppression] [-w | --tabWidth <length>] \
[-t | --tree] [-T | --treeWithComments] [-J | --treeWithJavadoc] [-j | --javadocTree] \
[-V | --version] [-b | --branch-matching-xpath <xpathQuery>] [-h | --help] \
[-e | --exclude <excludedPath>] [-E | --executeIgnoredModules] [-d | --debug] \
[-x | --exclude-regexp <excludedPathPattern>] \ file...
Checkstyle will process the specified files and by default report violations 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 - Specifies the output
format. Valid values: xml, plain for XMLLogger
and DefaultLogger respectively.
Defaults to plain.
-p propertiesFile - Sets the property files to load.
-o file - Sets the output file. Defaults to stdout.
-s line:column - Prints xpath suppressions at the file's line and column
position.
Argument is the line and column number (separated by a : ) in the file
that the suppression should be generated for. The option cannot be used
with other options and requires exactly one file to run on to be specified.
ATTENTION: generated result will have few queries, joined by pipe(|).
Together they will match all AST nodes on specified line
and column. You need to choose only one and recheck that it works. Usage of all of them is
also ok, but might result in undesirable matching and suppress other issues.
-g,--generate-xpath-suppression - Generates to output a suppression xml
to use to suppress all violations from user's config. Instead of printing every violation,
all violations will be catched and single suppressions xml file will be printed out.
Used only
with -c option. Output location can be specified with -o option.
-w, --tabWidth length - Sets the length of the tab character. Used only with
-s option. Default value is 8.
-t, --tree - Prints 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 - Prints Abstract Syntax Tree(AST) with comment nodes
of the checked file. The option cannot be used with other options and requires exactly
one file to run on to be specified.
-J, --treeWithJavadoc - Prints 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 with other options and requires exactly one
file to run on to be specified.
-j, --javadocTree - Prints 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. The option
cannot be used other options and requires exactly one file to run on to be specified.
-d, --debug - Prints all debug logging of CheckStyle utility.
-e, --exclude excludedPath - Directory/file to exclude from
CheckStyle. The path can be the full, absolute path, or relative to the current path.
Multiple excludes are allowed.
-x, --exclude-regexp excludedPathPattern - Directory/file pattern to
exclude from CheckStyle. Multiple excludes are allowed.
-V, --version - print product version and exit. Any other option is ignored.
-b, --branch-matching-xpath xpathQuery
- Shows Abstract Syntax Tree(AST) branches that match given XPath query.
-h, --help - print usage help message and exit. Any other option is ignored.
-E, --executeIgnoredModules - Allows ignored modules to be run.
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.
CLI is implemented by means of picocli library. Our CLI supports definition of arguments in file by means of AtFiles feature and also command line completion in Bash or ZSH Unix shells, see how to make it here.
It is possible to run Checkstyle directly from the JAR file using
the -jar option. Download latest
checkstyle-8.40-all.jar.
An example of run would be:
java -jar checkstyle-8.40-all.jar -c /sun_checks.xml MyClass.java
java -jar checkstyle-8.40-all.jar -c /google_checks.xml MyClass.java
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-8.40-all.jar.
An example of run would be (path to java file is optional):
java -cp checkstyle-8.40-all.jar com.puppycrawl.tools.checkstyle.gui.Main \
MyClass.java
Download and compile:
git clone https://github.com/checkstyle/checkstyle.git
cd checkstyle
mvn clean compile
Run validation with arguments:
mvn exec:java -Dexec.mainClass="com.puppycrawl.tools.checkstyle.Main" \
-Dexec.args="-c /sun_checks.xml src/main/java"
Run UI application for file :
mvn exec:java -Dexec.mainClass="com.puppycrawl.tools.checkstyle.gui.Main" -Dexec.args=\
"src/main/java/com/puppycrawl/tools/checkstyle/Checker.java"
Build all jars, and launch CLI from new build:
mvn clean package -Passembly
java -jar target/checkstyle-X.X-SNAPSHOT-all.jar -c /sun_checks.xml MyClass.java
The easiest way is to include
checkstyle-8.40-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
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml Check.java
Run checkstyle with configuration file
docs/sun_checks.xml on all Java files in a directory
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml src/
Run checkstyle with configuration file
docs/sun_checks.xml on a file and provide a system
property
java -Dcheckstyle.cache.file=target/cachefile com.puppycrawl.tools.checkstyle.Main \
-c docs/sun_checks.xml Check.java
Run checkstyle with configuration file
docs/sun_checks.xml on a file and use properties in a
file
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml \
-p myCheckstyle.properties Check.java
Run checkstyle with configuration file
docs/sun_checks.xml on a file and output to a file in
XML format
java com.puppycrawl.tools.checkstyle.Main -c docs/sun_checks.xml -f xml \
-o build/checkstyle_errors.xml Check.java
Run checkstyle with custom module(s) (Root module, Checks, etc) in configuration file:
java -classpath MyCustom.jar;checkstyle-8.40-all.jar \
com.puppycrawl.tools.checkstyle.Main -c config.xml Check.java
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.