Migrating from v1

This page lists what changes when moving from cpp-linter v1 (the Python package) to v2 (this Rust project). Most options keep their names, short flags and meaning, so many command lines work unchanged. The sections below cover the differences.

Deprecated options

v1 option	v2 behavior	What to do
-j, --jobs	Files are always analyzed in parallel. The value is still parsed as an integer, then ignored with a deprecation warning.	Remove the option.

Renamed or merged options

v1 option	v2 option	Notes
-d, --tidy-review	-P, --pr-review	v2 posts one review with suggestions from both clang-tidy and clang-format. The old names still work as aliases of --pr-review, so -d true now also enables clang-format suggestions.
-m, --format-review	-P, --pr-review	Same as above. -m true now also enables clang-tidy suggestions.
-F, --fix	-F, --gen-patch	See Fixes are written to a patch. --fix is kept as an alias.

The old names can still be given together, as in v1 (for example --tidy-review=true --format-review=false). Reviews are enabled if any of the given values is true.

Changed defaults

Option	v1 default	v2 default
-l, --lines-changed-only	false	true
-i, --ignore	.github	.github and target

Because --lines-changed-only is true by default and implies --files-changed-only, v2 analyzes only the added lines of changed files unless told otherwise. To keep the v1 behavior of analyzing every line of every source file, including files under target, pass:

cpp-linter --lines-changed-only=false --files-changed-only=false --ignore=.github

Fixes are written to a patch

In v1, --fix applied clang-format fixes in place, editing the files in the working tree.

In v2, cpp-linter never modifies the working tree. --gen-patch (alias --fix) writes one patch file that combines the clang-format and clang-tidy fixes. Its path is printed in the log and, in CI, set as the fix-patch-path output. By default the patch is written to .cpp-linter-cache/auto-fix.patch in the --repo-root folder. --gen-patch-path (or the GEN_PATCH_PATH environment variable) chooses another path and implies --gen-patch. To apply the fixes locally:

export GEN_PATCH_PATH=fixes.patch
cpp-linter
# The patch is only written when there are fixes.
if [ -f "$GEN_PATCH_PATH" ]; then git apply "$GEN_PATCH_PATH"; fi

A clang-tidy fix can also change a file that was not analyzed. Those parts are left out of the patch and listed as skipped in the log and in the comments, so apply them by hand.

Clang tools are installed for you

v1 expects clang-format and clang-tidy to be installed already, for example with clang-tools-pip. --version only selects which installed version to use.

In v2, -V, --version also accepts a version requirement (for example 16 or >=10, <13). If no matching tools are found on the PATH or in the cache, v2 installs them. It tries the system package manager first when allowed (on by default in CI, see --mod-sys and --no-mod-sys), then PyPI wheels, then static binaries built by cpp-linter. A path to an install location works as in v1. With a blank string (the default), v2 uses the installed tools and does not install anything, so the run fails if they are missing.

Running -V without a value prints the cpp-linter version, like the version subcommand.

Relative paths

In v2, a relative path given to --database, --gen-patch-path, --summary-output-file or --sarif-file is resolved against the current working directory, not against --repo-root.

• --database behaves as in v1 1.15 and later.
• --summary-output-file was resolved against --repo-root in v1. If you set --repo-root to a sub-folder and pass a relative summary path, prefix it with that sub-folder or use an absolute path.

With the default --repo-root of ., nothing changes.

New in v2

• --sarif-file writes clang-tidy diagnostics as a SARIF 2.1.0 file, for example to upload to GitHub code scanning.
• --gen-patch and --gen-patch-path produce one patch of the clang-format and clang-tidy fixes, described above.
• --mod-sys and --no-mod-sys control whether system package managers may be used to install the clang tools.