Content

Description

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.

Command line usage

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(s) or folder(s) ...

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:

Command Line Options

Option Description
-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, sarif, plain for XMLLogger, SarifLogger, 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. Note that the 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 This option is used to display the Abstract Syntax Tree (AST) without any comments of the specified file. It can only be used on a single file and cannot be combined with other options.
-T, --treeWithComments This option is used to display the Abstract Syntax Tree (AST) with comment nodes excluding Javadoc of the specified file. It can only be used on a single file and cannot be combined with other options.
-J, --treeWithJavadoc This option is used to display the Abstract Syntax Tree (AST) with Javadoc nodes of the specified file. It can only be used on a single file and cannot be combined with other options.
-j, --javadocTree This option is used to print the Parse Tree of the Javadoc comment. The file has to contain only Javadoc comment content excluding '/**' and '*/' at the beginning and at the end respectively. It can only be used on a single file and cannot be combined with other options.
-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 Prints product version and exits. Any other option is ignored.
-b, --branch-matching-xpath xpathQuery Shows Abstract Syntax Tree(AST) branches that match given XPath query.
-h, --help Prints usage help message and exits. 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 this link for details.

To define system property for execution look at system properties.

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.

Download and Run

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

          java -jar checkstyle-10.21.0-all.jar -c /sun_checks.xml MyClass.java
          java -jar checkstyle-10.21.0-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-10.21.0-all.jar. An example of run would be (path to java file is optional): 

          java -cp checkstyle-10.21.0-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

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,no-validations
          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-10.21.0-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 /sun_checks.xml on a filesystem 

          java com.puppycrawl.tools.checkstyle.Main -c /sun_checks.xml Check.java

Run checkstyle with configuration file /sun_checks.xml on all Java files in a directory 

          java com.puppycrawl.tools.checkstyle.Main -c /sun_checks.xml src/

Run checkstyle with configuration file /sun_checks.xml on a file and provide a system property 

          java -Dcheckstyle.cache.file=target/cachefile com.puppycrawl.tools.checkstyle.Main \
              -c /sun_checks.xml Check.java

Run checkstyle with configuration file /sun_checks.xml on a file and use properties in a file 

          java com.puppycrawl.tools.checkstyle.Main -c /sun_checks.xml \
              -p myCheckstyle.properties Check.java

Run checkstyle with configuration file /sun_checks.xml on a file and output to a file in XML format 

          java com.puppycrawl.tools.checkstyle.Main -c /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-10.21.0-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.