Pull/merge request check is available only in the Enterprise license. You can request a trial Enterprise license here.
The commit and the branch pull/merge analysis mode allow you to analyze only those files that have changed relative to the current state of the branch (the one the commit or pull/merge request is made to). This reduces the analysis time and simplifies the review of its results: the analyzer's report contains warnings issued for errors in the modified files.
This document describes the general principles of the pull/merge request analysis. You can find examples for specific CIs in the following documentation sections:
To analyze files that were changed during the branch merge, the files must be separated from all other files in the project. To do this, after the merge is done, you need to get the difference between the HEAD branch from where the pull/merge request is made and the branch where the changes will be made.
Let's look at the commit tree:
In this case, a 'quickFix' branch was created. After work is completed in the branch, a pull/merge request opens. Use the following command to get the difference between the current state of the 'master' branch and the last commit in the 'quickFix' branch (you have to be on the 'quickFix' branch at the time it is executed):
git diff --name-only HEAD master > .pvs-pr.list
This way you get a list of modified files relative to the latest commits in the 'master' and 'quickFix' branches. The names of the modified files will be saved in '.pvs-pr.list'.
Note. In the example of getting the files for analysis, we use the 'git' version control system. However, you can use any version control system that allows you to get a list of modified files.
To check the sent pull/merge request, you need to analyze the received file list.
In this section, you can find examples of commands for getting a list of modified files.
For Git:
To get a list of modified files before a commit, execute the command:
git diff --cached --name-only > .pvs-pr.list
To get a list of modified files between two commits, execute the command:
git diff --name-only CommitA CommitB > .pvs-pr.list
For SVN:
On Windows, you can execute the following command in PowerShell:
Write-Host (svn status | Select-String -Pattern '^[AM]\W*(.*)'
| %{$_.Matches.Groups[1].value}) -Separator "`b`n" > .pvs-pr.lits
On Linux:
svn status -q | grep -oP "^[M|A]\W*\K(.*)" > .pvs-pr.list
For Mercurial:
hg log --template "{files % '{file}\n'}\n" > .pvs-pr.list
For Perforce:
p4 diff -f -sa > .pvs-pr.list
Most version control systems (VCSs) support tracking events in a repository using special hooks. Usually, hooks are regular script files that the VCS runs. They can be used both on the client side (local developer machine) and on the VCS server (if you have your own VCS server). Using hooks on the VCS server enables you to configure a global policy for all developers in the company.
Each version control system has its own scenarios for using hooks. To learn more, please consult the documentation for your VCS.
You can integrate PVS-Studio directly into the VCS server. Follow the plan.
Keep in mind that executing the hooks is usually a blocking operation. It means that until the hook is executed, the commit or push operations will not close. Hence, using hooks can slow down the process of pushing changes to the repository.
Note: this scenario is quite difficult to implement, and we strongly recommend you use the VCS hooks only to create CI system triggers.
To check the list of files, pass a text file that contains absolute or relative paths to the files for analysis to the analyzer (relative paths will be expanded according to the working directory). Write each of the paths on a new line. Text that is not the path to the source-code file is ignored (this may be useful for commenting).
Example of the contents of a file with paths:
D:\MyProj\Tests.cs
D:\MyProj\Common.cs
D:\MyProj\Form.cs
Below are the options to run the analysis for different languages and operating systems.
To check C# files, use the 'PVS-Studio_Cmd' utility for Windows and 'pvs-studio-dotnet' for Linux and macOS.
The path to the file that contains the list of files for analysis is passed using the '-f' argument (detailed information about the arguments see in the documentation). The format of this file is described in the "File list checking mode" section.
You can check the return code to see if there are any analyzer warnings. The return codes are described in the documentation.
Example of a command to run the analysis:
PVS-Studio_Cmd.exe -t MyProject.sln ^
-f .pvs-pr.list ^
-o Analysis_Report.json
Files from '.pvs-pr.list' contained in the 'MyProject.sln' solution will be analyzed. The analysis results will be saved to the 'Analysis_Report.json' file.
Example of a command to run the analysis:
pvs-studio-dotnet -t MyProject.sln \
-f .pvs-pr.list \
-o Analysis_Report.json
Files from '.pvs-pr.list' contained in the 'MyProject.sln' solution will be analyzed. The analysis results will be saved to the 'Analysis_Report.json' file.
To check C and C++ files, use the following utilities:
The check method for each utility is described below.
The first launch of the analysis generates a dependency file of all the project's source files from the header files. The analyzer will update it automatically on subsequent runs. It is possible to create/update the dependency file without running the analysis. This process will be described for each of the utilities in the corresponding section.
Note. The way to analyze project files that use the MSBuild system is described in the "PVS-Studio_Cmd (Windows, Visual Studio\MSBuild)" section.
Depending on the operating system on which the analysis is performed, the utility will have different names:
The examples in this documentation use the 'pvs-studio-analyzer' name. The scenario to analyze files with 'CompilerCommandsAnalyzer.exe' is similar to that described here.
To use 'pvs-studio-analyzer', generate either the 'compile_commands.json' file, or a file with the results of the compilation trace (relevant only for Linux). The analyzer needs these files to have information about the compilation of specific files.
Generating 'compile_commands.json'
See the documentation for ways to generate the 'compile_commands.json' file.
Generating a trace file (Linux only)
See the documentation for ways to generate the trace file. By default, the result of tracing is written to the 'strace_out' file.
There are two options for analysis using a trace file. You can either perform a full tracing of the entire project's build at each start, or you can cache the result of the tracing and use it.
The downside of the first method is that a full tracing contradicts the idea of a quick check of commits or pull/merge requests.
The second way is bad because the analysis result may be incomplete if the dependency structure of source files changes after the tracing (for example, a new #include will be added to one of the source files).
For this reason, we do not recommend the use of the file list checking with the trace log for commit or pull/merge request checking. In case you are able to do an incremental build during the commit checking, consider using the incremental analysis mode.
Example of commands to analyze files and to update dependencies
Let's look at an example of using 'pvs-studio-analyzer'. The path to the file that contains the list of files for analysis is passed using the '-S' argument (detailed information about the utility's arguments see in the documentation). The format of this file is described in the "File list checking mode" section.
Note. If the compilation information was obtained using the compilation trace mode, the trace file is passed using the '-f' flag (by default, its name is 'strace_out').
Example of a command to analyze files:
pvs-studio-analyzer analyze -S .pvs-pr.list \
-f compile_commands.json \
-o Analysis_Report.json
This command generates a report with the result of checking the files contained in '.pvs-pr.list'. The analysis results will be saved to the 'Analysis_Report.json' file.
To generate or update a dependency file without starting the analysis, use the '‑‑regenerate-depend-info' flag with the 'skip-analysis' key. The command to update will look as follows:
pvs-studio-analyzer analyze -S .pvs-pr.list \
-f compile_commands.json \
–-regenerate-depend-info skip-analysis
Use the '‑‑regenerate-depend-info' flag with the 'run-analysis' key to force an update of the dependency cache with the subsequent start of the analysis.
By default, the dependency cache file is generated in the '.PVS-Studio' folder, which is created in the working directory. The cache is contained in the 'depend_info.json' file.
Getting information about the presence/absence of warnings in the analyzer report
To get information about the presence of analyzer warnings, use the utilities:
Here's documentation on these utilities.
Example of using 'PlogConverter.exe':
PlogConverter.exe Analysis_Report.json ^
-t html ^
-n PVS-Studio ^
--indicateWarnings
Example of using 'plog-converter':
plog-converter Analysis_Report.json \
-t html \
-n PVS-Studio \
--indicate-warnings
The path to the file with the analysis results is passed as the first command line argument. Use the '-t' argument to specify the format in which the report should be saved. The '-n' argument specifies the file name of the converted report. '‑‑indicateWarnings' for 'PlogConverter.exe ' and '‑‑indicate-warnings' for 'plog-converter' flags allow you to set the return code 2 if there are analyzer warnings in the report.
The path to the file that contains the list of files for analysis is passed using the '-f' argument (detailed information about the arguments see in the documentation). The format of this file is described in the "File list checking mode" section.
Example of a command to run the analysis:
CLMonitor.exe analyze -l "Analysis_Report.json" ^
-f ".pvs-pr.list"
This command will generate a report with the result of checking the files contained in '.pvs-pr.list'. The analysis results will be saved to the 'Analysis_Report.json' file.
To get information about the presence of analyzer warnings, you can use the 'PlogConverter' utility: If there are no analyzer warnings, the return code is 0. If there are warnings, the return code is 2. Here's documentation on these utilities.
Example of using 'PlogConverter':
PlogConverter.exe Analysis_Report.json \
-t html \
-n PVS-Studio \
--indicate-warnings
The path to the file with the analysis results is passed as the first command line argument. Use the '-t' argument to specify the format in which the report should be saved. The '-n' argument specifies the file name of the converted report. '‑‑indicateWarnings' for 'PlogConverter.exe ' and '‑‑indicate-warnings' for 'plog-converter' flags allow you to set the return code 2 if there are analyzer warnings in the report.
If the needed files with code are included in a Visual Studio project that uses the MSBuild system, the analysis is performed with the PVS-Studio_Cmd utility.
The path to the file that contains the list of files for analysis is passed using the '-f' argument (detailed information about the arguments see in the documentation). The format of this file is described in the section "File list checking mode".
You can check the return code to see if there are any analyzer warnings. The return codes are described in the documentation.
Example of a command to run the analysis:
PVS-Studio_Cmd.exe -t MyProject.sln ^
-f .pvs-pr.list ^
-o Analysis_Report.json
Files from the '.pvs-pr.list' contained in the 'MyProject.sln' solution will be analyzed. The analysis results will be saved to the 'Analysis_Report.json' file.
To update dependencies without running the analysis, use the '-W':
PVS-Studio_Cmd.exe -t MyProject.sln ^
-f .pvs-pr.list ^
-W
Use the '-G' flag to force an update of the dependency cache with the subsequent start of the analysis.
By default, the dependency cache file is generated at the project level and saved to the '.pvs-studio' folder. The file containing the cache has a name of the 'projectName.vcxproj.deps.json' form (the part of the file name, in our case it is 'projectName.vcxproj', corresponds to the project name). Accordingly, if you analyze the files belonging to the same solution but to different projects, the '.pvs-studio' folder with the dependency file will be created in the directory of each project.
You can change the directory where the cache is saved. To do this, use the '-D' parameter. The path to the directory where you want to save the cache is passed as the parameter's value.
To set relative paths in dependency caches, use the '-R' flag. You need to pass the path as an argument to the flag. According to this path, the paths in the dependency cache files will be expanded.
To check Java files, use the 'pvs-studio.jar ' utility. You can find the detailed information about the utility and its arguments in the documentation.
The path to the file that contains the list of files to be analyzed is passed using the '‑‑analyze-only-list' flag. The format of this file is described in the "File list checking mode" section.
To analyze the list of files, you also need to pass the path to the project containing these files. To do this, use the '-s' argument. The '-e' argument defines the classpath. If you need to use multiple classpath entities, separate them by a space.
Example of a command to run the analysis:
java -jar pvs-studio.jar -s projectDir ^
--analyze-only-list .pvs-pr.list ^
-e Lib1.jar Lib2.jar ^
-j4 ^
-o report.json ^
-O json ^
--user-name userName ^
--license-key key
As a result, the files recorded in the '.pvs-pr.list' will be analyzed. The analysis results will be saved to the 'report.json' file.
To get information about the presence of warnings, use the '‑‑fail-on-warnings' flag. When it is used, the analyzer returns code 53 if there are warnings in the analysis results.