=encoding utf8

=head1 NAME

spotbugs - launch SpotBugs from the command line

=head1 SYNOPSIS

spotbugs [I<options>]

=head1 DESCRIPTION

SpotBugs is a program to find bugs in Java programs. It looks for instances of
“bug patterns” — code instances that are likely to be errors.

=head1 REQUIREMENTS

To use SpotBugs, you need a runtime environment compatible with Java version
1.8 or later. SpotBugs is platform independent, and is known to run on
GNU/Linux, Windows, and MacOS X platforms.

You should have at least 512 MB of memory to use SpotBugs. To analyze very
large projects, more memory may be needed.

=head1 SUPPORTED JAVA VERSION

SpotBugs is built by JDK8, and run on JRE8 and newer versions.

SpotBugs can scan bytecode (class files) generated by JDK8 and newer versions.
However, support for Java 11 and newer is still experimental. Visit issue
tracker to find known problems.

SpotBugs does not support bytecode (class files) generated by outdated JDK such
as 10, 9, 7 and older versions.

=head1 WRAPPER SCRIPT OPTIONS

The SpotBugs wrapper scripts support the following command-line options. Note
that these command line options are not handled by the SpotBugs program per se;
rather, they are handled by the wrapper script.

=over

=item B<-jvmArgs> I<args>

Specifies arguments to pass to the JVM. For example, you might want to set a
JVM property:

    $ spotbugs -textui -jvmArgs "-Duser.language=ja" myApp.jar

=item B<-javahome> I<directory>

Specifies the directory containing the JRE (Java Runtime Environment) to use to
execute FindBugs.

=item B<-maxHeap> I<size>

Specifies the maximum Java heap size in megabytes. The default is 256. More
memory may be required to analyze very large programs or libraries.

=item B<-debug>

Prints a trace of detectors run and classes analyzed to standard output. Useful
for troubleshooting unexpected analysis failures.

=item B<-property> I<name>=I<value>

This option sets a system property. SpotBugs uses system properties to
configure analysis options. See L<Analysis
Properties|https://spotbugs.readthedocs.io/en/latest/analysisprops.html>. You
can use this option multiple times in order to set multiple properties. Note:
In most versions of Windows, the I<name>=I<value> string must be in quotes.

=back

=head1 OPTIONS

This section describes the command line options supported by SpotBugs. These
command line options may be used when invoking SpotBugs directly, or when using
a wrapper script.

=head2 Common command-line options

These options may be used with both the GUI and command-line interfaces.

=over

=item B<-effort>[:B<min>|B<less>|B<default>|B<more>|B<max>]

Set analysis effort level. The B<-effort:min> disables several analyses that
increase precision but also increase memory consumption. You may want to try
this option if you find that SpotBugs with the B<-effort:less> still runs out
of memory, or takes an unusually long time to complete its analysis. The
B<-effort:less> disables some analyses that increase precision but also
increase memory consumption. You may want to try this option if you find that
SpotBugs with the B<-effort:more>/B<-effort:default> runs out of memory, or
takes an unusually long time to complete its analysis. The B<-effort:more> runs
several analyses to find bugs, this is the B<-effort:default>. The
B<-effort:max> enable analyses which increase precision and find more bugs, but
which may require more memory and take more time to complete. See
L<Effort|https://spotbugs.readthedocs.io/en/latest/effort.html>.

=item B<-project> I<project>

Specify a project to be analyzed. The project file you specify should be one
that was created using the GUI interface. It will typically end in the
extension C<.fb> or C<.fbp>.

=item B<-pluginList> I<jar1>[;I<jar2>,…]:

Specify list of plugin Jar files to load.

=item B<-home> I<home directory>

Specify SpotBugs home directory.

=item B<-adjustExperimental>

Lower priority of experimental Bug Patterns.

=item B<-workHard>

Ensure analysis effort is at least B<default>.

=item B<-conserveSpace>

Same as B<-effort:min> (for backward compatibility).

=back

=head2 GUI Options

These options are only accepted by the Graphical User Interface.

=over

=item B<-look>:B<plastic>|B<gtk>|B<native>

Set Swing look and feel.

=back

=head2 Text UI Options

These options are only accepted by the Text User Interface.

=over

=item B<-sortByClass>=I<filepath>

Sort reported bug instances by class name.

From SpotBugs 4.5.0, this option receives a file path like
B<-sortByClass>=I<path/to/spotbugs.txt>. It is also supported to set multiple
reports like B<-xml=spotbugs.xml> B<-sortByClass=spotbugs.txt>.

=item B<-include> I<filterFile.xml>

Only report bug instances that match the filter specified by I<filterFile.xml>.
See L<Filter file|https://spotbugs.readthedocs.io/en/latest/filter.html>.

=item B<-exclude> I<filterFile.xml>

Report all bug instances except those matching the filter specified by
I<filterFile.xml>. See L<Filter
file|https://spotbugs.readthedocs.io/en/latest/filter.html>.

=item B<-onlyAnalyze> I<com.foobar.MyClass,com.foobar.mypkg.,!com.foobar.mypkg.ExcludedClass*>

Restrict analysis to find bugs to given comma-separated list of classes and
packages. Unlike filtering, this option avoids running analysis on classes and
packages that are not explicitly matched: for large projects, this may greatly
reduce the amount of time needed to run the analysis. (However, some detectors
may produce inaccurate results if they aren't run on the entire application.)
Classes should be specified using their full classnames (including package),
and packages should be specified in the same way they would in a Java import
statement to import all classes in the package (i.e., add C<.*> to the full
name of the package). Replace C<.*> with C<.-> to also analyze all subpackages.
Items starting with C<!> are treated as exclusions, removing otherwise-included
classes from analysis.

=item B<-low>

Report all bugs.

=item B<-medium>

Report medium and high priority bugs. This is the default setting.

=item B<-high>

Report only high priority bugs.

=item B<-relaxed>

Relaxed reporting mode. For many detectors, this option suppresses the
heuristics used to avoid reporting false positives.

=item B<-xml>=I<filepath>

Produce the bug reports as XML. The XML data produced may be viewed in the GUI
at a later time. You may also specify this option as B<-xml:withMessages>; when
this variant of the option is used, the XML output will contain human-readable
messages describing the warnings contained in the file. XML files generated
this way are easy to transform into reports.

From SpotBugs 4.5.0, this option receives a file path like
B<-xml:withMessages>=I<path/to/spotbugs.xml>. It is also supported to set
multiple reports like B<-xml>=I<spotbugs.xml> B<-html>=I<spotbugs.html>.

=item B<-html>=I<filepath>

Generate HTML output. By default, SpotBugs will use the F<default.xsl> XSLT
stylesheet to generate the HTML: you can find this file in F<spotbugs.jar>, or
in the SpotBugs source or binary distributions. Variants of this option include
B<-html:plain.xsl>, B<-html:fancy.xsl> and B<-html:fancy-hist.xsl>. The
F<plain.xsl> stylesheet does not use Javascript or DOM, and may work better
with older web browsers, or for printing. The F<fancy.xsl> stylesheet uses DOM
and Javascript for navigation and CSS for visual presentation. The
F<fancy-hist.xsl> an evolution of F<fancy.xsl> stylesheet. It makes an
extensive use of DOM and Javascript for dynamically filtering the lists of
bugs.

If you want to specify your own XSLT stylesheet to perform the transformation
to HTML, specify the option as B<-html>:I<myStylesheet.xsl>, where
I<myStylesheet.xsl> is the filename of the stylesheet you want to use.

From SpotBugs 4.5.0, this option receives a file path like
B<-html:fancy-hist.xsl>=I<path/to/spotbugs.html>. It is also supported to set
multiple reports like B<-xml>=F<spotbugs.xml> B<-html>=F<spotbugs.html>.

=item B<-sarif>=I<filepath>

Produce the bug reports in SARIF 2.1.0.

From SpotBugs 4.5.0, this option receives a file path like
B<-sarif>=I<path/to/spotbugs.sarif>. It is also supported to set multiple
reports like B<-xml>=F<spotbugs.xml> B<-sarif>=F<spotbugs.sarif>.

=item B<-emacs>=I<filepath>

Produce the bug reports in Emacs format.

=item B<-xdocs>=I<filepath>

Produce the bug reports in xdoc XML format for use with Apache Maven.

=item B<-output> I<filename>

This argument is deprecated. Use report type option like
B<-xml>=F<spotbugs.xml> instead.

=item B<-outputFile> I<filename>

This argument is deprecated. Use report type option like
B<-xml>=F<spotbugs.xml> instead.

=item B<-nested>[:B<true>|B<false>]

This option enables or disables scanning of nested jar and zip files found in
the list of files and directories to be analyzed. By default, scanning of
nested jar/zip files is enabled. To disable it, add -nested:false to the
command line arguments.

=item B<-auxclasspath> I<classpath>

Set the auxiliary classpath for analysis. This classpath should include all jar
files and directories containing classes that are part of the program being
analyzed but you do not want to have analyzed for bugs.

=item B<-auxclasspathFromInput>

Read the auxiliary classpath for analysis from standard input, each line adds
new entry to the auxiliary classpath for analysis.

=item B<-auxclasspathFromFile> I<filepath>

Read the auxiliary classpath for analysis from file, each line adds new entry
to the auxiliary classpath for analysis.

=item B<-analyzeFromFile> I<filepath>

Read the files to analyze from file, each line adds new entry to the classpath
for analysis.

=item B<-userPrefs> I<edu.umd.cs.findbugs.core.prefs>

Set the path of the user preferences file to use, which might override some of
the options above. Specifying userPrefs as first argument would mean some later
options will override them, as last argument would mean they will override some
previous options). This rationale behind this option is to reuse SpotBugs
Eclipse project settings for command line execution.

=item B<-showPlugins>

Show list of available detector plugins.

=back

=head2 Output options

=over

=item B<-timestampNow>

Set timestamp of results to be current time.

=item B<-quiet>

Suppress error messages.

=item B<-longBugCodes>

Report long bug codes.

=item B<-progress>

Display progress in terminal window.

=item B<-release> I<release name>

Set the release name of the analyzed application.

=item B<-maxRank> I<rank>

Only report issues with a bug rank at least as scary as that provided.

=item B<-dontCombineWarnings>

Don't combine warnings that differ only in line number.

=item B<-train>[:I<outputDir>]

Save training data (experimental); output dir defaults to F<.>.

=item B<-useTraining>[:I<inputDir>]

Use training data (experimental); input dir defaults to F<.>.

=item B<-redoAnalysis> I<filename>

Redo analysis using configuration from previous analysis.

=item B<-sourceInfo> I<filename>

Specify source info file (line numbers for fields/classes).

=item B<-projectName> I<project name>

Descriptive name of project.

=item B<-reanalyze> I<filename>

Redo analysis in provided file.

=back

=head2 Output filtering options

=over

=item B<-bugCategories> I<cat1>[,I<cat2>,…]

Only report bugs in given categories.

=item B<-excludeBugs> I<baseline bugs>

Exclude bugs that are also reported in the baseline xml output.

=item B<-applySuppression>

Exclude any bugs that match suppression filter loaded from fbp file.

=back

=head2 Detector (visitor) configuration options

=over

=item B<-visitors> I<v1>[,I<v2>,…]

Run only named visitors.

=item B<-omitVisitors> I<v1>[,I<v2>,…]

Omit named visitors.

=item B<-chooseVisitors> +I<v1>,-I<v2>,…

Selectively enable/disable detectors.

=item B<-choosePlugins> +I<p1>,-I<p2>,…

Selectively enable/disable plugins.

=item B<-adjustPriority> I<v1>=(B<raise>|B<lower>)[,…]

Raise/lower priority of warnings for given visitor(s).

=back

=head2 Project configuration options

=over

=item B<-sourcepath> I<source path>

Set source path for analyzed classes.

=item B<-exitcode>

Set exit code of process.

=item B<-noClassOk>

Output empty warning file if no classes are specified.

=item B<-xargs>

Get list of classfiles/jarfiles from standard input rather than command line.

=item B<-bugReporters> I<name>,I<name2>,-I<name3>

Bug reporter decorators to explicitly enable/disable.

=item B<-printConfiguration>

Print configuration and exit, without running analysis.

=back

=head1 LICENSE

SpotBugs is released under version 2.1 of the L<LGPL
License|https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt>.

=head1 SEE ALSO

L<https://spotbugs.github.io/>.