Notifying the developer teams (blame-notifier utility)
The blame-notifier utility is meant for automating the process of notifying developers who have committed the code in the repository for which the PVS-Studio analyzer has issued warnings. The analyzer report is passed to the blame-notifier with specification of additional parameters; the utility finds files that triggered warnings and generates an HTML-report for each "guilty" developer. It is also possible to send a full report: it will contain all warnings related to each "guilty" developer.
The blame-notifier utility is available only under the PVS-Studio Enterprise license. You can request the trial Enterprise license here.
Note. The utility's name differs under different platforms. Under Windows it has the name BlameNotifier.exe, under Linux and macOS - blame-notifier. If we aren't talking about the utility for a specific OS, the name "blame-notifier" is used to avoid duplication in this document.
The blame-notifier utility on Linux and macOS requires .NET Runtime 8.0.
Installation
On Windows
The BlameNotifier utility can be found in the PVS-Studio installation directory ("C:\Program Files (x86)\PVS-Studio\" by default).
On Linux
Installation from repositories
For debian-based systems:
wget -q -O - https://files.pvs-studio.com/etc/pubkey.txt | \
sudo apt-key add -
sudo wget -O /etc/apt/sources.list.d/viva64.list \
https://files.pvs-studio.com/etc/viva64.list
sudo apt-get update
sudo apt-get install blame-notifier
For yum-based systems:
wget -O /etc/yum.repos.d/viva64.repo \
https://files.pvs-studio.com/etc/viva64.repo
yum update
yum install blame-notifier
For zypper-based systems:
wget -q -O /tmp/viva64.key https://files.pvs-studio.com/etc/pubkey.txt
sudo rpm --import /tmp/viva64.key
sudo zypper ar -f https://files.pvs-studio.com/rpm viva64
sudo zypper update
sudo zypper install blame-notifier
Direct links to download.
On macOS
Installation from Homebrew
Installation:
brew install viva64/pvs-studio/blame-notifier
Update:
brew upgrade blame-notifier
Direct links to download.
Usage
Use the "‑‑help" flag to display basic information about the utility:
blame-notifier --help
An example of using the blame-notifier utility (in one line):
blame-notifier path/to/PVS-Studio.log
--VCS Git
--recipientsList recipients.txt
--server ... --sender ... --login ... --password ...
Utility options
Here's a quick description of the utility's parameters:
- ‑‑VCS (or -v): required parameter: a type of version control system that the utility will be working with. Supported systems: Git, Svn, Mercurial, Perforce.
- ‑‑recipientsList (or -r): the path to the text file, containing the list of report recipients. The file format is described below.
- ‑‑srcRoot (or -t): sets up a replacement for a special "SourceTreeRoot" marker. If the analyzer's log was generated with this marker, this parameter is needed to restore the paths to files.
- ‑‑analyzer (or -a): filters warnings according to the mask. More details about the filtration masks are given below.
- ‑‑excludedCodes (or -e): sets up the list of warnings (separated with ",") that shouldn't be included in the resulting report.
- ‑‑settings (or -c): sets the path to the PVS-Studio settings file. This flag is relevant only when working on Windows. BlameNotifier will read settings of disabled warnings from the passed settings file. In fact, this parameter expands the list of disabled warnings of the parameter "‑‑excludedCodes".
- ‑‑server (or -x): required parameter: SMTP server for mail sending.
- ‑‑sender (or -s): required parameter: sender's email address.
- ‑‑login (or -l): required parameter: username for authorization.
- ‑‑password (or -w): password for authorization.
- ‑‑port (or -p): mail delivery port (25 by default).
- ‑‑days (or -d): show analyzer warnings for the last N days, where N is a positive value. If the value is not specified or set to 0, all warnings for the entire time period will be displayed.
- ‑‑sortByDate (or -S): sort analysis results by modification date of the source code that triggered analyzer warning. Off by default.
- ‑‑maxTasks (or -m): the maximum number of concurrently running blame-processes. By default, or if a negative number is set, blame-notifier will use 2* N processes (where N is the number of CPU cores).
- ‑‑progress (or -g): turn loggings on/off. Off by default.
- ‑‑enableSSL: enable SSL protocol. Off by default.
- ‑‑vcsBasedRecipientsList: automatically retrieve a list of recipients from the specified VCS. This flag is available for the following VCSs: Perforce. Off by default.
- ‑‑messageSubject: the message subject. If this parameter is not specified, blame-notifier sends a message with a default subject: "Full PVS-Studio Analysis Results for Solution: <SolutionName>"
- ‑‑messageAttachment: a list of paths to files which should be attached to the message. If you need to attach several files, separate the paths with the ';' mark and enclose the list in quotation marks.
- ‑‑svnUsername: username for authorization in SVN.
- ‑‑svnPassword: password for authorization in SVN
When using the utility, at least one of the flags, via which the list of reports recipients is set, has to be specified: '‑‑recipientsList' or '‑‑vcsBasedRecipientsList'.
If necessary, these flags can be used jointly.
Report recipients file format
File format with a list of report recipients:
# Recipients of the full report
username_1 *email_1
...
username_N *email_N
# Recipients of individually assigned warnings
username_1 email_1
...
username_N email_N
You can comment on the line with the symbol "#". For full report recipients, you need to add the "*" symbol at the beginning or end of an email address. The full report will include all warnings sorted by developers.
Format of masks filtration
The filtering masks look like this: MessageType:MessageLevels.
"MessageType" can take one of the following values: GA, OP, 64, CS, MISRA, Fail.
"MessageLevels" can take a value of 1 to 3.
A combination of different masks through ";" is possible (without spaces), for example:
--analyzer=GA:1,2;64:1
In this case, general-analysis warnings (GA) of 1 and 2 levels, and 64-bit warnings of the 1 level will be handled.