Skip to content

website: in CLI help ouput, mark config parameter as optional #17506

@clach04

Description

@clach04

I have read check documentation: https://checkstyle.org/checks/xxxxxx/nameofaffectedcheck.html
I have downloaded the latest checkstyle from: https://checkstyle.org/cmdline.html#Download_and_Run
I have executed the cli and showed it below, as cli describes the problem better than 1,000 words

# Not applicable
/var/tmp $ javac YOUR_FILE.java


# Not applicable - this is the bug ;-)
/var/tmp $ cat config.xml
Deliberately not present

# Empty
/var/tmp $ cat YOUR_FILE.java


# Not applicable - this is the bug ;-)
/var/tmp $ RUN_LOCALE="-Duser.language=en -Duser.country=US"
/var/tmp $ java $RUN_LOCALE -jar checkstyle-X.XX-all.jar -c config.xml YOUR_FILE.java
#[[PLACE YOUR OUTPUT HERE]]

Describe what you expect in detail.

Help output indicates files and directories are required, with many optional flags, including config file:

Details
C:\tmp>C:\java\openjdk-21.0.2_windows-x64_bin\jdk-21.0.2\bin\java.exe -jar C:\Users\clach04\Downloads\checkstyle-10.26.1-all.jar --version
Checkstyle version: 10.26.1

C:\tmp>C:\java\openjdk-21.0.2_windows-x64_bin\jdk-21.0.2\bin\java.exe -jar C:\Users\clach04\Downloads\checkstyle-10.26.1-all.jar --help
Usage: checkstyle [-dEgGhjJtTV] [-b=<xpath>] [-c=<configurationFile>] [-f=<format>]
                  [-o=<outputPath>] [-p=<propertiesFile>] [-s=<suppressionLineColumnNumber>]
                  [-w=<tabWidth>] [-e=<exclude>]... [-x=<excludeRegex>]... <files or folders>...
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 or folders>... 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 xpath 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.
  -G, --generate-checks-and-files-suppression
                            Generates to output a suppression xml that will have suppress elements
                              with "checks" and "files" attributes only 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.

I.e. [-c=<configurationFile>] is in square brackets which typical denotes optional. From the error returned when ran with a non-empty directory (e.g. create a single empty java file) get error:

mkdir c:\tmp\emptydir
echo "" > c:\tmp\emptydir\test.java
C:\tmp>C:\java\openjdk-21.0.2_windows-x64_bin\jdk-21.0.2\bin\java.exe -jar C:\Users\clach04\Downloads\checkstyle-10.26.1-all.jar c:\tmp\emptydir
Must specify a config XML file.

I think the help output is incorrect. The behavior seems reasonable.


Still not clear ???
see example - https://checkstyle.org/report_issue.html#How_to_report_a_bug.3F

ATTENTION: FAILURE TO FOLLOW THE ABOVE TEMPLATE WILL RESULT IN THE ISSUE BEING CLOSED.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions