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.3-all.jar.
An example of run would be:
java -jar checkstyle-10.21.3-all.jar -c /sun_checks.xml MyClass.java
java -jar checkstyle-10.21.3-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.3-all.jar.
An example of run would be (path to java file is optional):
java -cp checkstyle-10.21.3-all.jar com.puppycrawl.tools.checkstyle.gui.Main \
MyClass.java
Examples
1. Using Configuration File (-c, --configurationFile)
Goal: Run Checkstyle using the settings defined in the specified XML configuration file (config.xml) to check the provided Java source files.
Command:
java -jar checkstyle-10.21.3-all.jar -c config.xml Test.java
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="FallThrough"/>
</module>
</module>
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
Starting audit...
[ERROR] Test.java:17:17: Fall through from previous branch of the switch statement.
[FallThrough]
Audit done.
Checkstyle ends with 1 errors.
2. Specifying Output Format (-f, --format)
Goal: Output the audit results in a Xml Format instead of the default plain text.
Command:
java -jar checkstyle-10.21.3-all.jar -c config.xml -f xml Test.java
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="FallThrough"/>
</module>
</module>
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
<?xml version="1.0" encoding="UTF-8"?>
<checkstyle version="10.21.3">
<file name="Test.java">
<error line="17" column="17" severity="error"
message="Fall through from previous branch of switch statement"
source="com.puppycrawl.tools.checkstyle.checks.coding.FallThroughCheck"/>
</file>
</checkstyle>
Checkstyle ends with 1 errors.
3. Using a Properties File (-p, --propertiesFile)
Goal: Load custom properties into Checkstyle from a properties file to enforce a header check.
Command:
java -jar checkstyle-10.21.3-all.jar -c config.xml -p checkstyle.properties Test.java
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="Header">
<property name="headerFile" value="${checkstyle.header.file}"/>
<property name="charset" value="${checkstyle.header.charset}"/>
</module>
<module name="TreeWalker">
<module name="FallThrough"/>
</module>
</module>
Content of checkstyle.properties:
checkstyle.header.file=file:header.txt
checkstyle.header.charset=UTF-8
Content of header.txt:
/**
* This is the required header for all source files.
*/
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
* Note: This file intentionally does not contain the required header.
*/
class Test {
/**
* Some summary on method.
*/
public void bar() {
System.out.println("Configured with properties!");
}
}
Output:
Starting audit...
[ERROR] Test.java:2: Line does not match expected header line of ' * This is the
required header for all source files.'. [Header]
Audit done.
Checkstyle ends with 1 errors.
4. Specifying an Output File (-o, --outputPath)
Goal: Direct the Checkstyle output into a designated file rather than printing to standard output.
Command:
java -jar checkstyle-10.21.3-all.jar -c config.xml -o results.txt Test.java
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="FallThrough"/>
</module>
</module>
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Content of results.txt:
Starting audit...
[ERROR] Test.java:17:17: Fall through from previous branch of the switch statement. [FallThrough]
Audit done.
5. Printing XPath Suppressions (-s, --suppressionLineColumnNumber)
Goal: Generate XPath suppressions for the violation at the specified line and column.
Command:
java -jar checkstyle-10.21.3-all.jar -s 17:17 Test.java
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
java -jar checkstyle-10.21.3-all.jar -s 17:17 Test.java
/COMPILATION_UNIT/CLASS_DEF[./IDENT[@text='Test']]/OBJBLOCK/METHOD_DEF[
./IDENT[@text='foo']]/SLIST/LITERAL_WHILE/SLIST/LITERAL_SWITCH/CASE_GROUP
[./LITERAL_CASE/EXPR/NUM_INT[@text='3']]/COMPILATION_UNIT/CLASS_DEF
[./IDENT[@text='Test']]/OBJBLOCK/METHOD_DEF[./IDENT[@text='foo']]
/SLIST/LITERAL_WHILE/SLIST/LITERAL_SWITCH/CASE_GROUP/LITERAL_CASE
6. Generating Suppressions XML (-g, --generate-xpath-suppression)
Goal: Generate an XML file containing suppressions for all violations using the experimental XPath suppression filter.
Command:
java -jar checkstyle-10.21.3-all.jar -c config.xml -g -o suppressions.xml Test.java
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="FallThrough"/>
</module>
</module>
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Content of suppressions.xml:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suppressions PUBLIC
"-//Checkstyle//DTD SuppressionXpathFilter Experimental Configuration 1.2//EN"
"https://checkstyle.org/dtds/suppressions_1_2_xpath_experimental.dtd">
<suppressions>
<suppress-xpath
files="Test.java"
checks="FallThroughCheck"
query="/COMPILATION_UNIT/CLASS_DEF[./IDENT[@text='Test']]/OBJBLOCK/METHOD_DEF
./IDENT[@text='foo']]/SLIST/LITERAL_WHILE/SLIST/LITERAL_SWITCH/CASE_GROUP[
./LITERAL_CASE/EXPR/NUM_INT[@text='3']]"/>
</suppressions>
7. Setting Tab Width (-w, --tabWidth)
Goal:
Set the length of the tab character when using the -s
option,
and generate the suppression XPath query for the violation.
java -jar checkstyle-10.21.3-all.jar -s 17:17 --tabWidth 4 Test.java
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
/COMPILATION_UNIT/CLASS_DEF[./IDENT[@text='Test']]/OBJBLOCK/METHOD_DEF
./IDENT[@text='foo']]/SLIST/LITERAL_WHILE/SLIST/LITERAL_SWITCH/CASE_GROUP
[./LITERAL_CASE/EXPR/NUM_INT[@text='3']]/COMPILATION_UNIT/CLASS_DEF[./IDENT
[@text='Test']]/OBJBLOCK/METHOD_DEF[./IDENT[@text='foo']]/SLIST/LITERAL_WHILE
/SLIST/LITERAL_SWITCH/CASE_GROUP/LITERAL_CASE
8. Displaying Abstract Syntax Tree (-t, --tree)
Goal: Display the Abstract Syntax Tree (AST) of a file without comments.
Command:
java -jar checkstyle-10.21.3-all.jar -t Test.java
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
COMPILATION_UNIT -> COMPILATION_UNIT [6:0]
`--CLASS_DEF -> CLASS_DEF [6:0]
|--MODIFIERS -> MODIFIERS [6:0]
|--LITERAL_CLASS -> class [6:0]
|--IDENT -> Test [6:6]
`--OBJBLOCK -> OBJBLOCK [6:11]
|--LCURLY -> { [6:11]
|--METHOD_DEF -> METHOD_DEF [10:4]
| |--MODIFIERS -> MODIFIERS [10:4]
| | `--LITERAL_PUBLIC -> public [10:4]
| |--TYPE -> TYPE [10:11]
| | `--LITERAL_VOID -> void [10:11]
| |--IDENT -> foo [10:16]
| |--LPAREN -> ( [10:19]
| |--PARAMETERS -> PARAMETERS [10:20]
| |--RPAREN -> ) [10:20]
| `--SLIST -> { [10:22]
| |--VARIABLE_DEF -> VARIABLE_DEF [11:8]
| | |--MODIFIERS -> MODIFIERS [11:8]
| | |--TYPE -> TYPE [11:8]
| | | `--LITERAL_INT -> int [11:8]
| | |--IDENT -> i [11:12]
| | `--ASSIGN -> = [11:14]
| | `--EXPR -> EXPR [11:16]
| | `--NUM_INT -> 0 [11:16]
| |--SEMI -> ; [11:17]
| |--LITERAL_WHILE -> while [12:8]
| | |--LPAREN -> ( [12:14]
| | |--EXPR -> EXPR [12:17]
| | | `--GE -> >= [12:17]
| | | |--IDENT -> i [12:15]
| | | `--NUM_INT -> 0 [12:20]
| | |--RPAREN -> ) [12:21]
| | `--SLIST -> { [12:23]
| | |--LITERAL_SWITCH -> switch [13:12]
| | | |--LPAREN -> ( [13:19]
| | | |--EXPR -> EXPR [13:20]
| | | | `--IDENT -> i [13:20]
| | | |--RPAREN -> ) [13:21]
| | | |--LCURLY -> { [13:23]
| | | |--CASE_GROUP -> CASE_GROUP [14:16]
| | | | |--LITERAL_CASE -> case [14:16]
| | | | | |--EXPR -> EXPR [14:21]
| | | | | | `--NUM_INT -> 1 [14:21]
| | | | | `--COLON -> : [14:22]
| | | | |--LITERAL_CASE -> case [15:16]
| | | | | |--EXPR -> EXPR [15:21]
| | | | | | `--NUM_INT -> 2 [15:21]
| | | | | `--COLON -> : [15:22]
| | | | `--SLIST -> SLIST [16:21]
| | | | |--EXPR -> EXPR [16:21]
| | | | | `--POST_INC -> ++ [16:21]
| | | | | `--IDENT -> i [16:20]
| | | | `--SEMI -> ; [16:23]
| | | |--CASE_GROUP -> CASE_GROUP [17:16]
| | | | |--LITERAL_CASE -> case [17:16]
| | | | | |--EXPR -> EXPR [17:21]
| | | | | | `--NUM_INT -> 3 [17:21]
| | | | | `--COLON -> : [17:22]
| | | | `--SLIST -> SLIST [18:21]
| | | | |--EXPR -> EXPR [18:21]
| | | | | `--POST_INC -> ++ [18:21]
| | | | | `--IDENT -> i [18:20]
| | | | `--SEMI -> ; [18:23]
| | | `--RCURLY -> } [19:12]
| | `--RCURLY -> } [20:8]
| `--RCURLY -> } [21:4]
`--RCURLY -> } [22:0]
9. Displaying AST with Comments (-T, --treeWithComments)
Goal: Display the AST including comment nodes, but excluding Javadoc.
Command:
java -jar checkstyle-10.21.3-all.jar --treeWithComments Test.java
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
COMPILATION_UNIT -> COMPILATION_UNIT [6:0]
`--CLASS_DEF -> CLASS_DEF [6:0]
|--MODIFIERS -> MODIFIERS [6:0]
|--BLOCK_COMMENT_BEGIN -> /* [1:0]
| |--COMMENT_CONTENT -> *\r\n * Javadoc summary.\r\n *\r\n * Some description.\r\n [1:2]
| `--BLOCK_COMMENT_END -> */ [5:1]
|--LITERAL_CLASS -> class [6:0]
|--IDENT -> Test [6:6]
`--OBJBLOCK -> OBJBLOCK [6:11]
|--LCURLY -> { [6:11]
|--METHOD_DEF -> METHOD_DEF [10:4]
| |--MODIFIERS -> MODIFIERS [10:4]
| | |--BLOCK_COMMENT_BEGIN -> /* [7:4]
| | | |--COMMENT_CONTENT -> *\r\n * Some summary on method.\r\n [7:6]
| | | `--BLOCK_COMMENT_END -> */ [9:5]
| | `--LITERAL_PUBLIC -> public [10:4]
| |--TYPE -> TYPE [10:11]
| | `--LITERAL_VOID -> void [10:11]
| |--IDENT -> foo [10:16]
| |--LPAREN -> ( [10:19]
| |--PARAMETERS -> PARAMETERS [10:20]
| |--RPAREN -> ) [10:20]
| `--SLIST -> { [10:22]
| |--VARIABLE_DEF -> VARIABLE_DEF [11:8]
| | |--MODIFIERS -> MODIFIERS [11:8]
| | |--TYPE -> TYPE [11:8]
| | | `--LITERAL_INT -> int [11:8]
| | |--IDENT -> i [11:12]
| | `--ASSIGN -> = [11:14]
| | `--EXPR -> EXPR [11:16]
| | `--NUM_INT -> 0 [11:16]
| |--SEMI -> ; [11:17]
| |--LITERAL_WHILE -> while [12:8]
| | |--LPAREN -> ( [12:14]
| | |--EXPR -> EXPR [12:17]
| | | `--GE -> >= [12:17]
| | | |--IDENT -> i [12:15]
| | | `--NUM_INT -> 0 [12:20]
| | |--RPAREN -> ) [12:21]
| | `--SLIST -> { [12:23]
| | |--LITERAL_SWITCH -> switch [13:12]
| | | |--LPAREN -> ( [13:19]
| | | |--EXPR -> EXPR [13:20]
| | | | `--IDENT -> i [13:20]
| | | |--RPAREN -> ) [13:21]
| | | |--LCURLY -> { [13:23]
| | | |--CASE_GROUP -> CASE_GROUP [14:16]
| | | | |--LITERAL_CASE -> case [14:16]
| | | | | |--EXPR -> EXPR [14:21]
| | | | | | `--NUM_INT -> 1 [14:21]
| | | | | `--COLON -> : [14:22]
| | | | |--LITERAL_CASE -> case [15:16]
| | | | | |--EXPR -> EXPR [15:21]
| | | | | | `--NUM_INT -> 2 [15:21]
| | | | | `--COLON -> : [15:22]
| | | | `--SLIST -> SLIST [16:21]
| | | | |--EXPR -> EXPR [16:21]
| | | | | `--POST_INC -> ++ [16:21]
| | | | | `--IDENT -> i [16:20]
| | | | `--SEMI -> ; [16:23]
| | | |--CASE_GROUP -> CASE_GROUP [17:16]
| | | | |--LITERAL_CASE -> case [17:16]
| | | | | |--EXPR -> EXPR [17:21]
| | | | | | `--NUM_INT -> 3 [17:21]
| | | | | `--COLON -> : [17:22]
| | | | `--SLIST -> SLIST [18:21]
| | | | |--EXPR -> EXPR [18:21]
| | | | | `--POST_INC -> ++ [18:21]
| | | | | |--SINGLE_LINE_COMMENT -> // [17:24]
| | | | | | `--COMMENT_CONTENT -> violation\r\n [17:26]
| | | | | `--IDENT -> i [18:20]
| | | | `--SEMI -> ; [18:23]
| | | `--RCURLY -> } [19:12]
| | `--RCURLY -> } [20:8]
| `--RCURLY -> } [21:4]
`--RCURLY -> } [22:0]
10. Displaying AST with Javadoc (-J, --treeWithJavadoc)
Goal: Display the AST including Javadoc comment nodes.
Command:
java -jar checkstyle-10.21.3-all.jar --treeWithJavadoc Test.java
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
COMPILATION_UNIT -> COMPILATION_UNIT [6:0]
`--CLASS_DEF -> CLASS_DEF [6:0]
|--MODIFIERS -> MODIFIERS [6:0]
|--BLOCK_COMMENT_BEGIN -> /* [1:0]
| |--COMMENT_CONTENT -> *\r\n * Javadoc summary.\r\n *\r\n * Some description.\r\n [1:2]
| | `--JAVADOC -> JAVADOC [1:3]
| | |--NEWLINE -> \r\n [1:3]
| | |--LEADING_ASTERISK -> * [2:0]
| | |--TEXT -> Javadoc summary. [2:2]
| | |--NEWLINE -> \r\n [2:19]
| | |--LEADING_ASTERISK -> * [3:0]
| | |--NEWLINE -> \r\n [3:2]
| | |--LEADING_ASTERISK -> * [4:0]
| | |--TEXT -> Some description. [4:2]
| | |--NEWLINE -> \r\n [4:20]
| | |--TEXT -> [5:0]
| | `--EOF -> <EOF> [5:1]
| `--BLOCK_COMMENT_END -> */ [5:1]
|--LITERAL_CLASS -> class [6:0]
|--IDENT -> Test [6:6]
`--OBJBLOCK -> OBJBLOCK [6:11]
|--LCURLY -> { [6:11]
|--METHOD_DEF -> METHOD_DEF [10:4]
| |--MODIFIERS -> MODIFIERS [10:4]
| | |--BLOCK_COMMENT_BEGIN -> /* [7:4]
| | | |--COMMENT_CONTENT -> *\r\n * Some summary on method.\r\n [7:6]
| | | | `--JAVADOC -> JAVADOC [7:7]
| | | | |--NEWLINE -> \r\n [7:7]
| | | | |--LEADING_ASTERISK -> * [8:0]
| | | | |--TEXT -> Some summary on method. [8:6]
| | | | |--NEWLINE -> \r\n [8:30]
| | | | |--TEXT -> [9:0]
| | | | `--EOF -> <EOF> [9:5]
| | | `--BLOCK_COMMENT_END -> */ [9:5]
| | `--LITERAL_PUBLIC -> public [10:4]
| |--TYPE -> TYPE [10:11]
| | `--LITERAL_VOID -> void [10:11]
| |--IDENT -> foo [10:16]
| |--LPAREN -> ( [10:19]
| |--PARAMETERS -> PARAMETERS [10:20]
| |--RPAREN -> ) [10:20]
| `--SLIST -> { [10:22]
| |--VARIABLE_DEF -> VARIABLE_DEF [11:8]
| | |--MODIFIERS -> MODIFIERS [11:8]
| | |--TYPE -> TYPE [11:8]
| | | `--LITERAL_INT -> int [11:8]
| | |--IDENT -> i [11:12]
| | `--ASSIGN -> = [11:14]
| | `--EXPR -> EXPR [11:16]
| | `--NUM_INT -> 0 [11:16]
| |--SEMI -> ; [11:17]
| |--LITERAL_WHILE -> while [12:8]
| | |--LPAREN -> ( [12:14]
| | |--EXPR -> EXPR [12:17]
| | | `--GE -> >= [12:17]
| | | |--IDENT -> i [12:15]
| | | `--NUM_INT -> 0 [12:20]
| | |--RPAREN -> ) [12:21]
| | `--SLIST -> { [12:23]
| | |--LITERAL_SWITCH -> switch [13:12]
| | | |--LPAREN -> ( [13:19]
| | | |--EXPR -> EXPR [13:20]
| | | | `--IDENT -> i [13:20]
| | | |--RPAREN -> ) [13:21]
| | | |--LCURLY -> { [13:23]
| | | |--CASE_GROUP -> CASE_GROUP [14:16]
| | | | |--LITERAL_CASE -> case [14:16]
| | | | | |--EXPR -> EXPR [14:21]
| | | | | | `--NUM_INT -> 1 [14:21]
| | | | | `--COLON -> : [14:22]
| | | | |--LITERAL_CASE -> case [15:16]
| | | | | |--EXPR -> EXPR [15:21]
| | | | | | `--NUM_INT -> 2 [15:21]
| | | | | `--COLON -> : [15:22]
| | | | `--SLIST -> SLIST [16:21]
| | | | |--EXPR -> EXPR [16:21]
| | | | | `--POST_INC -> ++ [16:21]
| | | | | `--IDENT -> i [16:20]
| | | | `--SEMI -> ; [16:23]
| | | |--CASE_GROUP -> CASE_GROUP [17:16]
| | | | |--LITERAL_CASE -> case [17:16]
| | | | | |--EXPR -> EXPR [17:21]
| | | | | | `--NUM_INT -> 3 [17:21]
| | | | | `--COLON -> : [17:22]
| | | | `--SLIST -> SLIST [18:21]
| | | | |--EXPR -> EXPR [18:21]
| | | | | `--POST_INC -> ++ [18:21]
| | | | | |--SINGLE_LINE_COMMENT -> // [17:24]
| | | | | | `--COMMENT_CONTENT -> violation\r\n [17:26]
| | | | | `--IDENT -> i [18:20]
| | | | `--SEMI -> ; [18:23]
| | | `--RCURLY -> } [19:12]
| | `--RCURLY -> } [20:8]
| `--RCURLY -> } [21:4]
`--RCURLY -> } [22:0]
11. Printing Javadoc Parse Tree (-j, --javadocTree)
Goal: Print the full parse tree of a Javadoc comment extracted from a file.
Command:
java -jar checkstyle-10.21.3-all.jar --javadocTree Javadoc.txt
Content of Javadoc.txt:
/**
* This is a sample Javadoc comment.
* It spans multiple lines and includes tags.
* @param value Input value for processing.
* @return Processed result.
*/
Output:
JAVADOC -> JAVADOC [0:0]
|--TEXT -> /** [0:0]
|--NEWLINE -> \r\n [0:3]
|--LEADING_ASTERISK -> * [1:0]
|--TEXT -> This is a sample Javadoc comment. [1:2]
|--NEWLINE -> \r\n [1:36]
|--LEADING_ASTERISK -> * [2:0]
|--TEXT -> It spans multiple lines and includes tags. [2:2]
|--NEWLINE -> \r\n [2:45]
|--LEADING_ASTERISK -> * [3:0]
|--WS -> [3:2]
|--JAVADOC_TAG -> JAVADOC_TAG [3:3]
| |--PARAM_LITERAL -> @param [3:3]
| |--WS -> [3:9]
| |--PARAMETER_NAME -> value [3:10]
| |--WS -> [3:15]
| `--DESCRIPTION -> DESCRIPTION [3:16]
| |--TEXT -> Input value for processing. [3:16]
| `--NEWLINE -> \r\n [3:43]
|--LEADING_ASTERISK -> * [4:0]
|--WS -> [4:2]
|--JAVADOC_TAG -> JAVADOC_TAG [4:3]
| |--RETURN_LITERAL -> @return [4:3]
| |--WS -> [4:10]
| `--DESCRIPTION -> DESCRIPTION [4:11]
| |--TEXT -> Processed result. [4:11]
| |--NEWLINE -> \r\n [4:28]
| |--LEADING_ASTERISK -> * [5:0]
| `--TEXT -> / [5:2]
`--EOF -> <EOF> [5:3]
12. Debugging CheckStyle (-d, --debug)
Goal: Run Checkstyle in debug mode to produce detailed logging information and troubleshooting.
Command:
java -jar checkstyle-10.21.3-all.jar --debug -c config.xml Test.java
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="FallThrough"/>
</module>
</module>
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
Feb 17, 2025 11:55:59 PM com.puppycrawl.tools.checkstyle.Main runCli
FINE: Checkstyle debug logging enabled
Feb 17, 2025 11:55:59 PM com.puppycrawl.tools.checkstyle.Main runCli
FINE: Running Checkstyle with version: 10.21.3
Starting audit...
[ERROR] Test.java:17:17: Fall through from
previous branch of the switch statement. [FallThrough]
Audit done.
Checkstyle ends with 1 errors.
13. Excluding Specific Files/Directories (-e, --exclude)
Goal: Exclude designated files or directories from the Checkstyle audit so that they are not processed.
Command:
java -jar checkstyle-10.21.3-all.jar -c config.xml -e Test.java Other.java Test.java
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="FallThrough"/>
</module>
</module>
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
Starting audit...
Skipping excluded file: Test.java
Audit done.
14. Excluding Files Using Regular Expressions (-x, --exclude-regexp )
Goal: Exclude files or directories that match a given regular expression pattern while execution on folder 'src'.
Command:
java -jar checkstyle-10.21.3-all.jar -c config.xml --exclude-regexp ".*Test.*\.java" src
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="FallThrough"/>
</module>
</module>
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
Starting audit...
Skipping excluded file: Test.java
Audit done.
15. Displaying Checkstyle Version (-V, --version)
Goal: Print the current Checkstyle version information.
Command:
java -jar checkstyle-10.21.3-all.jar --version
Output:
Checkstyle 10.21.3
16. Matching AST Branches (-b, --branch-matching-xpath)
Goal: Show AST branches matching a given XPath query for the variable declaration of "x".
Command:
java -jar checkstyle-10.21.3-all.jar --branch-matching-xpath"/COMPILATION_UNIT/CLASS_DEF
/OBJBLOCK/METHOD_DEF/SLIST/VARIABLE_DEF[./IDENT[@text='x']]" Test.java
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
void foo() {
int x = 10;
}
}
Output:
COMPILATION_UNIT -> COMPILATION_UNIT [6:0]
`--CLASS_DEF -> CLASS_DEF [6:0]
`--OBJBLOCK -> OBJBLOCK [6:11]
|--METHOD_DEF -> METHOD_DEF [10:4]
| `--SLIST -> { [10:15]
| |--VARIABLE_DEF -> VARIABLE_DEF [11:8]
17. Displaying Help Message (-h, --help)
Goal: Display the full usage instructions for the Checkstyle CLI, detailing available options and syntax.
Command:
java -jar checkstyle-10.21.3-all.jar --help
Output:
Usage: checkstyle [-dEghjJtTV] [-b=<xpath>] [-c=<configurationFile>]
[-f=<format>] [-o=<outputPath>] [-p=<propertiesFile>]
[-s=<suppressionLineColumnNumber>] [-w=<tabWidth>]
[-e=<exclude>]...[-x=<excludeRegex>]...
<files>...
Checkstyle verifies that the specified source code files adhere to the specified rules.
By default, violations are reported to standard out in plain format.
Checkstyle requires a configuration XML file that configures the checks to apply.
<files>... One or more source files to verify
-b, --branch-matching-xpath=<xpath>
Shows Abstract Syntax Tree(AST) branches that match given XPath query.
-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.
-d, --debug Prints all debug logging of CheckStyle utility.
-e, --exclude=<exclude> Directory/file to exclude from Checkstyle.
The path can be the full,absolute path,
or relative to the current path. Multiple excludes are
allowed.
-E, --executeIgnoredModules
Allows ignored modules to be run.
-f=<format> Specifies the output format. Valid values: xml, sarif, plain for
XMLLogger, SarifLogger, and DefaultLogger respectively. Defaults to
plain.
-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.
-h, --help Show this help message and exit.
-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.
-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.
-o=<outputPath> Sets the output file. Defaults to stdout.
-p=<propertiesFile> Sets the property files to load.
-s=<suppressionLineColumnNumber>
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.
-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.
-V, --version Print version information and exit.
-w, --tabWidth=<tabWidth> Sets the length of the tab character.
Used only with -s option. Default value is 8.
-x, --exclude-regexp=<excludeRegex>
Directory/file pattern to exclude from Checkstyle. Multiple excludes
are allowed.
18. Executing Ignored Modules (-E, --executeIgnoredModules)
Goal: Force execution of modules that are normally ignored (e.g., those set with severity "ignore") so that any exceptions occurring within them are reported as errors.
Command:
java -jar checkstyle-10.21.3-all.jar -c config.xml --executeIgnoredModules Test.java
Content of config.xml:
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<property name="severity" value="ignore"/>
<module name="TreeWalker">
<module name="FallThrough"/>
<property name="severity" value="ignore"/>
</module>
</module>
Content of Test.java:
/**
* Javadoc summary.
*
* Some description.
*/
class Test {
/**
* Some summary on method.
*/
public void foo() {
int i = 0;
while (i >= 0) {
switch (i) {
case 1:
case 2:
i++;
case 3: // violation
i++;
}
}
}
}
Output:
Starting audit...
Audit done.
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.3-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.3-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.