# Работа с анализатором Go из командной строки В этой документации представлена работа с анализатором PVS\-Studio для Go c использованием командной строки\. Помимо CLI, PVS\-Studio предоставляет интеграцию с GoLand и Visual Studio Code\. Подробнее описано в соответствующих документациях: * [Использование расширения PVS\-Studio для Visual Studio Code](https://pvs-studio.ru/ru/docs/manual/6646/)\. * [Работа PVS\-Studio в JetBrains GoLand](https://pvs-studio.ru/ru/docs/manual/7190/)\. ## Установка Установка анализатора описана в [отдельной документации](https://pvs-studio.ru/ru/docs/manual/7187/)\. ## Ввод лицензии Перед началом использования анализатора необходимо активировать лицензию\. Ввод лицензии описан в [отдельной документации](https://pvs-studio.ru/ru/docs/manual/0046/)\. ## Быстрый старт Утилита имеет два режима работы: * `analyze` — утилита выполняет анализ переданного проекта; * `suppress` — утилита выполняет генерацию файла подавления\. Для получения информации обо всех доступных аргументах и флагах, необходимо выполнить команды: * `pvs-golang --help` * `pvs-golang analyze --help` * `pvs-golang suppress --help` Для запуска анализа проекта нужно воспользоваться командой `analyze` и передать путь до директории с Go проектом: ```cpp pvs-golang analyze /path/to/project ``` По итогам выполнения анализа утилита сохранит отчёт в текущей рабочей директории с именем `PVS-Studio.json` и вернёт [код возврата](https://pvs-studio.ru/ru/docs/manual/7194/#exit_codes)\. ## Аргументы и флаги режима 'analyze' Режим `analyze` имеет один аргумент — директория с проектом\. Ниже представлены флаги режима `analyze`\. ### \-\-analysis\-paths, \-P Определяет поведение анализатора на указанных путях\. Принимает строку следующего формата: ```cpp (mode=|)(,mode=|)* ``` где `mode` — поведение анализатора на указанном пути `` или glob\-паттерне ``\. Допустимые режимы: * `analyze` — анализатор проведёт анализ файлов, соответствующих указанному пути или glob\-паттерну; * `skip-analysis` — анализатор уберёт из анализа файлы, соответствующие указанному пути или glob\-паттерну\. Анализатор всегда изначально предполагает, что все исходные файлы должны быть проверены \(`analyze=*`\), даже при явной передаче флага\. Флаг может быть задан несколько раз, анализатор последовательно применит все указанные фильтры\. Например, нужно исключить из анализа директории `3rd-party` и `unittests`, но включить в анализ поддиректорию `3rd-party/lib1`: ```cpp pvs-golang analyze /path/to/project \ --analysis-paths "skip-analysis=*/3rd-party/*" \ --analysis-paths "skip-analysis=*/unittests/*" \ --analysis-paths "analyze=*/3rd-party/lib1/*" ``` ### \-\-source\-files, \-S Активирует проверку списка файлов\. Позволяет решить задачу [автоматической проверки коммитов и Pull/Merge Requests](https://pvs-studio.ru/ru/docs/manual/0055/) на стороне CI/CD\. В качестве аргумента принимает файл со списком путей или glob\-паттернов, которые необходимо проанализировать\. Каждый путь или glob\-паттерн должен быть записан отдельной строкой, например: ```cpp # content of the file src/source1.go src/source2.go ``` Если файл содержит относительные пути, то они будут раскрыты в абсолютные через текущую рабочую директорию\. Пример: ```cpp pvs-golang analyze /path/to/project \ --source-files fromCommit.txt ``` ### \-\-output, \-o Путь до результирующего отчёта анализатора\. Расширение файла, переданного в качестве аргумента, не влияет на формат содержимого отчёта\. Если необходимо выдать результат в `stdout`, то нужно передать символ `-` как аргумент флага\. Если флаг не передан, то по умолчанию отчёт запишется в текущей рабочей директории с именем `PVS-Studio.json`\. Пример: ```cpp pvs-golang analyze /path/to/project \ --output report.json ``` ### \-\-analysis\-config, \-c Позволяет задать конфигурацию анализа через файл в формате TOML\. Более подробно об этом способе настройки анализатора написано в [отдельной документации\.](https://pvs-studio.ru/ru/docs/manual/7193/) По умолчанию, утилита ищет файл `pvs-settings.toml` в директории, указанной для анализа\. Пример: ```cpp cd /path/to/project pvs-golang analyze . \ --analysis-config project-settings.toml ``` ### \-\-threads, \-j Задаёт количество потоков для анализа\. Представляет собой целое, неотрицательное число\. Если в качестве аргумента передано значение 0, то анализ будет распараллелен на все доступные логические ядра\. Если флаг не указан, то по умолчанию утилита распараллеливает работу на оптимальное количество потоков для анализа\. Пример: ```cpp pvs-golang analyze /path/to/project \ --threads 8 ``` ### \-\-file\-analysis\-timeout Определяет время, через которое будет остановлен анализ единичного файла \(таймаут\)\. Представляет собой строку формата `XXhYYmZZs`\. Если флаг не указан, то по умолчанию утилита останавливает анализ единичного файла через 10 минут\. Пример установки таймаута на 30 минут: ```cpp pvs-golang analyze /path/to/project \ --file-analysis-timeout 30m ``` ### \-\-source\-tree\-root, \-r Позволяет генерировать переносимые между машинами отчёты\. Представляет собой путь до директории, который будет заменяться в позициях предупреждений на специальный маркер `|?|`\. Пример: ```cpp pvs-golang analyze /path/to/project \ --source-tree-root /path/to/project ``` ### \-\-rules, \-R Позволяет управлять состоянием диагностических правил — включены \(`on`\) или выключены \(`off`\)\. Принимает строку следующего формата: ```cpp (RULE|RANGE|GROUP)=(on|off)(,(RULE|RANGE|GROUP)=(on|off))* ``` где: * `RULE` — диагностическое правило, которое записывается в формате `Vxxxx`\. Списки диагностических правил доступны здесь: [\[1\]](https://pvs-studio.ru/ru/docs/warnings/#GeneralAnalysisGolang) и [\[2\]](https://pvs-studio.ru/ru/docs/warnings/#OWASPGolang)\. * `RANGE` — закрытый диапазон диагностических правил, который записывается в формате `Vxxxx-Vyyyy`\. Число `xxxx` должно быть меньше `yyyy`\. * `GROUP` — группа диагностических правил\. Доступные группы: * `ALL` — все диагностические правила\. * `GA` — диагностические правила общего назначения\. * `OWASP` — диагностические правила для обнаружения отклонений от OWASP ASVS\. Анализатор всегда изначально предполагает, что включена только группа диагностических правил общего назначения \(`GA=on`\), даже при явной передаче флага\. Флаг может быть задан несколько раз: анализатор последовательно применит все указанные фильтры\. Пример отключения всех правил и включение только правил V8001–V8031: ```cpp pvs-golang analyze /path/to/project \ --rules ALL=off \ --rules V8001-V8031=on ``` ### \-\-security\-related\-issues Включает добавление [SEC\-меток](https://pvs-studio.ru/ru/docs/manual/7183/) в поле SAST предупреждений анализатора\. SEC\-метки отображают группы срабатываний анализатора согласно классификации критических ошибок из ГОСТ Р 71207\-2024\. Пример: ```cpp pvs-golang analyze /path/to/project \ --security-related-issues ``` ### \-\-indicate\-warnings, \-w При указании флага, утилита возвращает код 1, если отчёт содержит предупреждения после успешного завершения анализа\. Пример: ```cpp pvs-golang analyze /path/to/project \ –-indicate-warnings ``` ### \-\-no\-noise Позволяет не выдавать в результатах анализа предупреждения низкого уровня достоверности\. Пример: ```cpp pvs-golang analyze /path/to/project \ –-no-noise ``` ### \-\-suppress\-files, \-s Задаёт пути до [файлов подавления](https://pvs-studio.ru/ru/docs/manual/0032/) предупреждений анализатора\. Если флаг не указан, то по умолчанию утилита неявно ищет файл с названием `suppress_file.suppress.json` в директории анализа\. Флаг может быть задан несколько раз: анализатор читает все указанные файлы подавления\. Пример: ```cpp pvs-golang analyze /path/to/project \ --suppress-files /path/to/project/file1.suppress.json \ --suppress-files /path/to/project/file2.suppress.json ``` ### \-\-disable\-license\-expiration\-check Позволяет отключить проверку об истечении срока лицензии\. Если до окончания лицензии остаётся менее 30 дней, без указания флага утилита возвращает код 21 и записывает сообщение\. Пример: ```cpp pvs-golang analyze /path/to/project \ --disable-license-expiration-check ``` ### \-\-ignore\-analysis\-failures Позволяет игнорировать ненулевой код возврата при следующих некритичных ошибках: * неполный разбор кода; * превышение времени анализа; * неполная семантическая информация о проекте\. Пример: ```cpp pvs-golang analyze /path/to/project \ --ignore-analysis-failures ``` ### \-\-license\-file, \-l Позволяет задать произвольный путь до файла, содержащего информацию о лицензии\. На Windows лицензия должна содержаться в `[Settings.xml](https://pvs-studio.ru/ru/docs/manual/6653/)` файле, на Linux/macOS — в файле `[PVS-Studio.lic](https://pvs-studio.ru/ru/docs/manual/0046/)`\. Если флаг не указан, то по умолчанию утилита ищет лицензию, которая была введена стандартным способом на [Windows](https://pvs-studio.ru/ru/docs/manual/0046/#WindowsCLI) или [Linux/macOS](https://pvs-studio.ru/ru/docs/manual/0046/#UnixLikeCLI)\. Пример: ```cpp pvs-golang analyze /path/to/project \ --license-file /path/to/project/PVS-Studio.lic ``` ## Аргументы и флаги режима 'suppress' Режим `suppress` производит подавление предупреждений на основе переданных отчётов анализа\. Предупреждения, которые генерирует анализатор и которые соответствуют подавленным, не попадут в отчёт при следующих проверках проекта\. Более подробно об этом механизме написано в [отдельной документации](https://pvs-studio.ru/ru/docs/manual/0032/#ID3C24E2E40C)\. Режим принимает пути до отчётов анализа\. Подавленные предупреждения по умолчанию записываются в текущую рабочую директорию в файл с именем `suppress_file.suppress.json`\. Расположение файла может быть изменено соответствующим флагом, который будет описан ниже\. Если файл ранее существовал, то утилита дополнит его новыми предупреждениями\. Пример: ```cpp pvs-golang suppress /path/to/project/module1.report.json /path/to/project/module2.report.json ``` Ниже представлены флаги режима `suppress`\. ### \-\-output, \-o Путь до результирующего файла подавления\. При попытке передачи пути до директории в качестве аргумента будет выдана ошибка\. Если файл ранее существовал и является файлом подавления, то утилита дополнит его новыми предупреждениями\. Если необходимо выдать результат в `stdout`, то нужно передать символ `-` как аргумент флага\. Пример: ```cpp pvs-golang suppress /path/to/project/report.json \ --output /path/to/project/project.suppress.json ``` ## Коды возврата ### Режим 'analyze' * `0` — анализ успешно завершён\. * `1` — анализ успешно завершён и результирующий отчёт содержит предупреждения\. Этот код будет возвращен только при использовании флага `--indicate-warnings`\. * `2` — обнаружена некорректная конфигурация анализатора, заданная через интерфейс командной строки или файлы конфигурации\. * `3` — при работе утилиты возникла непредвиденная ошибка\. Обычно это сигнализирует о наличии ошибки в коде самой утилиты и сопровождается выведением дополнительной информации в `stderr`\. Если вам встретилась такая ошибка, пожалуйста, отправьте эту информацию нам через [форму обратной связи](https://pvs-studio.ru/ru/about-feedback/)\. * `4` — все файлы были исключены из анализа\. * `5` — имеются файлы, которые не удалось проанализировать \(например, произошла ошибка парсинга\)\. * `6` — имеются файлы, анализ которых был прерван по таймауту\. * `20` — истёк срок действия лицензии\. * `21` — срок действия лицензии истечёт через месяц\. * `22` — лицензия отсутствует или невалидна\. ### Режим 'suppress' * `0` — предупреждения из всех переданных отчетов были успешно подавлены\. * `1` — часть предупреждений из переданных отчетов не была подавлена из\-за некритичной ошибки\. * `2` — были указаны некорректные входные данные\. * `3` — при работе утилиты возникла непредвиденная ошибка\. Обычно это сигнализирует о наличии ошибки в коде самой утилиты и сопровождается выведением дополнительной информации в `stderr`\. Если вам встретилась такая ошибка, пожалуйста, отправьте эту информацию нам через [форму обратной связи](https://pvs-studio.ru/ru/about-feedback/)\.