Content

• Content
• Description
• Command line usage
• Download and Run
• Run after compilation
• Usage by Classpath update

Description

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.

Command line usage

java -D<property>=<value>  \
     com.puppycrawl.tools.checkstyle.Main \
     -c <configurationFile> \
     [-f <format>] [-p <propertiesFile>] [-o <file>] \
     [-t | --tree] [-T | --treeWithComments] [-J | treeWithJavadoc] [-j | --javadocTree] [-v] \
     file...
      

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

  
             * Test method.
             * @return true
  
            

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

Download and Run

It is possible to run Checkstyle directly from the JAR file using the -jar option. Download latest checkstyle-8.8-all.jar. An example of run would be:

java -jar checkstyle-8.8-all.jar -c /sun_checks.xml MyClass.java
java -jar checkstyle-8.8-all.jar -c /google_checks.xml MyClass.java
        

To run Checkstyle UI viewer for AST tree directly from the JAR file using the -jar option. Download latest checkstyle-8.8-all.jar. An example of run would be (path to java file is optional):

java -cp checkstyle-8.8-all.jar com.puppycrawl.tools.checkstyle.gui.Main MyClass.java
        

Run after compilation

Download and compile:

git clone https://github.com/checkstyle/checkstyle.git
cd checkstyle
mvn clean compile
        

mvn exec:java -Dexec.mainClass="com.puppycrawl.tools.checkstyle.Main" \
    -Dexec.args="-c /sun_checks.xml src/main/java "
        

mvn exec:java -Dexec.mainClass="com.puppycrawl.tools.checkstyle.gui.Main" \
    -Dexec.args="src/main/java/com/puppycrawl/tools/checkstyle/Checker.java"
        

mvn clean package -Passembly
java -jar target/checkstyle-X.X-SNAPSHOT-all.jar -c /sun_checks.xml MyClass.java
        

Usage by Classpath update

The easiest way is to include checkstyle-8.8-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.8-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.