Our website uses cookies to enhance your browsing experience.
Contents
This documentation describes how to use PVS-Studio analyzer for Go via the command line.
In addition to the CLI, PVS-Studio offers integration with GoLand and Visual Studio Code. Learn more from the dedicated documentation:
Information on how to install the analyzer is available in the dedicated documentation.
It is necessary to activate the license before using the analyzer. Learn how to enter the license in the dedicated documentation.
The utility has two modes:
analyze is used to analyze the specified project;suppress is used to generate a suppress file.To view information about all available arguments and flags, run the following commands:
pvs-golang --helppvs-golang analyze --helppvs-golang suppress --helpTo run a project analysis, use the analyze command and specify the path to the directory containing your Go project:
pvs-golang analyze /path/to/projectAfter the analysis is finished, the utility saves a report with the PVS-Studio.json filename in the current working directory and issues a return code.
The analyze mode takes one argument, which is the project directory.
The flags for the analyze mode are listed below.
Specifies how the analyzer behaves on the given paths. It accepts a string of the following format:
(mode=<path>|<glob>)(,mode=<path>|<glob>)*where mode defines the analyzer behavior for the specified <path> or <glob> pattern. The following modes are available:
analyze is used to analyze files that match the specified path or glob pattern;skip-analysis is used to exclude from the analysis files that match the specified path or glob pattern.By default, the analyzer assumes that every source file should be analyzed (analyze=*), even when you explicitly pass the flag. You can specify the flag multiple times, and the analyzer applies the filters in the order you provide them.
For example, the following configuration excludes the 3rd-party and unittests directories from the analysis while including the 3rd-party/lib1 subdirectory:
pvs-golang analyze /path/to/project \
--analysis-paths "skip-analysis=*/3rd-party/*" \
--analysis-paths "skip-analysis=*/unittests/*" \
--analysis-paths "analyze=*/3rd-party/lib1/*"Enables file list filtering, enabling the automatic analysis of commits and pull/merge requests as part of your CI/CD pipeline.
It takes a file containing a list of paths or glob patterns to analyze. Specify each path or glob pattern on a separate line, for example:
# content of the file
src/source1.go
src/source2.goRelative paths in the file will be expanded to absolute ones relative to the current working directory.
The example:
pvs-golang analyze /path/to/project \
--source-files fromCommit.txtSpecifies the path to the analyzer output report. The file extension you provide as an argument does not affect the report contents.
To output the report to stdout, pass - as the argument.
If you omit this flag, by default, the analyzer writes the report to PVS-Studio.json in the current working directory.
The example:
pvs-golang analyze /path/to/project \
--output report.jsonEnables specifying the analysis configuration via a TOML file. For more information about this configuration, see the dedicated documentation.
By default, the utility looks for the pvs-settings.toml file in the directory specified for the analysis.
The example:
cd /path/to/project
pvs-golang analyze . \
--analysis-config project-settings.tomlSpecifies the number of analysis threads. The value should be a non-negative integer.
If you specify 0, the analyzer uses all available logical CPU cores.
If you omit this option, the utility automatically selects the optimal number of threads for the analysis.
The example:
pvs-golang analyze /path/to/project \
--threads 8Specifies the timeout for analyzing a single file.
The value should use the XXhYYmZZs format.
If you omit this option, the utility stops analyzing a file after ten minutes by default.
The following example sets the timeout to 30 minutes:
pvs-golang analyze /path/to/project \
--file-analysis-timeout 30mEnables generation of machine-independent reports. Specify a directory path, and the analyzer replaces it with the special |?| marker in warning locations.
The example:
pvs-golang analyze /path/to/project \
--source-tree-root /path/to/projectControls whether diagnostic rules are enabled (on) or disabled (off).
Accepts a string of the following format:
(RULE|RANGE|GROUP)=(on|off)(,(RULE|RANGE|GROUP)=(on|off))*Where:
RULE is a diagnostic rule written in the Vxxxx format. Lists of available diagnostic rules are provided here and here.RANGE is an inclusive range of diagnostic rules specified as Vxxxx-Vyyyy, where xxxx should be less than yyyy.GROUP is a group of diagnostic rules. The following groups are available:ALL are all diagnostic rules.GA are general analysis diagnostic rules.OWASP are diagnostic rules for detecting violations of the OWASP ASVS.By default, the analyzer enables only the general analysis rule group (GA=on), even if you explicitly specify this option. You can specify the flag multiple times, and the analyzer applies the filters in the order you provide them.
The following example disables all diagnostic rules and enables only rules V8001 through V8031:
pvs-golang analyze /path/to/project \
--rules ALL=off \
--rules V8001-V8031=onEnables adding SEC marks to the SAST field of the analyzer warnings.
The example:
pvs-golang analyze /path/to/project \
--security-related-issuesReturns code 1 if the resulting report contains warnings after the analysis completes normally.
The example:
pvs-golang analyze /path/to/project \
–-indicate-warningsPrevents warnings of low certainty level from appearing in the analysis results.
The example:
pvs-golang analyze /path/to/project \
–-no-noiseThe flag sets paths to suppress files.
If no flag is specified, by default, the utility implicitly searches for a file named suppress_file.suppress.json in the analysis directory.
You can pass the flag multiple times; the analyzer reads all the specified suppress files.
The example:
pvs-golang analyze /path/to/project \
--suppress-files /path/to/project/file1.suppress.json \
--suppress-files /path/to/project/file2.suppress.jsonDisables the license expiration check. Without this flag, if the license expires in less than 30 days, the utility returns code 21 and logs a message.
The example:
pvs-golang analyze /path/to/project \
--disable-license-expiration-checkEnables non-zero return codes to be ignored for the following non-critical errors:
The example:
pvs-golang analyze /path/to/project \
--ignore-analysis-failuresSpecifies an arbitrary path to the file containing license information. On Windows, the license should be stored in the Settings.xml file; on Linux/macOS, it should be stored in the PVS-Studio.lic file.
If the flag is not specified, the utility searches for a license entered using the standard method on Windows or Linux/macOS by default.
The example:
pvs-golang analyze /path/to/project \
--license-file /path/to/project/PVS-Studio.licThe suppress mode suppresses warnings based on the provided analysis reports. Analyzer warnings that match the suppressed ones will not appear in reports generated during future project checks. For more information about this mechanism, see the dedicated documentation.
The mode accepts paths to analysis reports. By default, suppressed warnings are saved in the current working directory to the suppress_file.suppress.json file. You can change the file location using the corresponding flag described below. If the file already exists, the utility will add new warnings to it.
The example:
pvs-golang suppress /path/to/project/module1.report.json
/path/to/project/module2.report.jsonThe flags for the suppress mode are listed below.
The path to the resulting suppress file.
If you pass a directory path as an argument, the utility issues an error.
If the file already exists and is a suppression file, the utility will add new warnings to it.
To output the report to stdout, pass - as the argument.
The example:
pvs-golang suppress /path/to/project/report.json \
--output /path/to/project/project.suppress.json0—the analysis completed successfully.1—the analysis completed successfully, but the resulting report contains warnings. This code is returned only when the --indicate-warnings flag is used.2—an invalid analyzer configuration specified via the command-line interface or configuration files was detected.3—an unexpected error occurred while running the utility. This usually indicates errors in the utility itself and is accompanied by additional information printed to stderr. If you encounter this error, please send us the details using the feedback form.4—all files were excluded from analysis.5—some files could not be analyzed (for example, due to a parsing error).6—some files could not be analyzed because the analysis timed out.20—the license has expired.21—the license will expire in one month.22—the license is missing or invalid.0—warnings from all provided reports were successfully suppressed.1—some warnings from the provided reports were not suppressed due to a non-critical error.2—invalid input data was provided.3—an unexpected error occurred while running the utility. This usually indicates errors in the utility itself and is accompanied by additional information printed to stderr. If you encounter this error, please send us the details using the feedback form.Was this page helpful?
