Content

Content
Description
Command line usage
Download and Run
Examples
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 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.

Command:


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.