From e253c4d5c0995cf39823d2a34fd274d0f03f7efd Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 30 Oct 2026 19:27:44 +0000 Subject: [PATCH 1/5] docs: add a v1 to v2 migration guide --- docs/docs/migration.md | 91 ++++++++++++++++++++++++++++++++++++++++++ docs/mkdocs.yml | 1 + 2 files changed, 92 insertions(+) create mode 100644 docs/docs/migration.md diff --git a/docs/docs/migration.md b/docs/docs/migration.md new file mode 100644 index 00000000..e448af8e --- /dev/null +++ b/docs/docs/migration.md @@ -0,0 +1,91 @@ + + +[lines-changed-only]: cli.md#-l-lines-changed-only +[files-changed-only]: cli.md#-f-files-changed-only +[version]: cli.md#-v-version +[mod-sys]: cli.md#-mod-sys +[no-mod-sys]: cli.md#-no-mod-sys +[ignore]: cli.md#-i-ignore +[database]: cli.md#-p-database +[repo-root]: cli.md#-r-repo-root +[pr-review]: cli.md#-p-pr-review +[gen-patch]: cli.md#-f-gen-patch +[sarif-file]: cli.md#-sarif-file + +# 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. + +## Removed options + +| v1 option | v2 behavior | What to do | +|---|---|---| +| `-j`, `--jobs` | Files are always analyzed in parallel. | Remove the option. v2 exits with an "unexpected argument" error if it is given. | + +## Renamed or merged options + +| v1 option | v2 option | Notes | +|---|---|---| +| `-d`, `--tidy-review` | [`-P`, `--pr-review`][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`][pr-review] | Same as above. `-m true` now also enables clang-tidy suggestions. | +| `-F`, `--fix` | [`-F`, `--gen-patch`][gen-patch] | See [Fixes are written to a patch](#fixes-are-written-to-a-patch). `--fix` is kept as an alias. | + +## Changed defaults + +| Option | v1 default | v2 default | +|---|---|---| +| [`-l`, `--lines-changed-only`][lines-changed-only] | `false` | `true` | +| [`-i`, `--ignore`][ignore] | `.github` | `.github` and `target` | + +Because `--lines-changed-only` is `true` by default and implies +[`--files-changed-only`][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, pass: + +```shell +cpp-linter --lines-changed-only=false --files-changed-only=false +``` + +## 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`][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. To apply the fixes locally: + +```shell +cpp-linter --gen-patch +git apply path/to/the/printed/patch +``` + +## Clang tools are installed for you + +v1 expects clang-format and clang-tidy to be installed already, for example with +[clang-tools-pip](https://github.com/cpp-linter/clang-tools-pip). `--version` only selects which +installed version to use. + +In v2, [`-V`, `--version`][version] also accepts a version requirement (for example `16`, `=12.0.1` +or `>=10, <13`). If no matching tools are found on the system, v2 downloads them. It tries +PyPI wheels first, then the system package manager (on by default in CI, see +[`--mod-sys`][mod-sys] and [`--no-mod-sys`][no-mod-sys]), then static binaries built by +cpp-linter. A path to an install location and a blank string (the default installed version) work +as in v1. + +Running `-V` without a value prints the cpp-linter version, like the `version` subcommand. + +## Paths relative to the repository root + +A relative [`--database`][database] path is resolved against [`--repo-root`][repo-root] in v2. In +v1 (1.15 and later) it is resolved against the current working directory. Both give the same result +with the default `--repo-root` of `.`. If you set `--repo-root` to a sub-folder, pass the database +path relative to that folder, or use an absolute path. + +## New in v2 + +- [`--sarif-file`][sarif-file] writes clang-tidy diagnostics as a SARIF 2.1.0 file, for example to + upload to GitHub code scanning. +- [`--gen-patch`][gen-patch] produces a patch of all fixes, described above. +- [`--mod-sys`][mod-sys] and [`--no-mod-sys`][no-mod-sys] control whether system package managers + may be used to install the clang tools. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 296ec385..2d205019 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -7,6 +7,7 @@ edit_uri: "edit/main/docs/docs/" nav: - index.md - cli.md + - migration.md - pr-review-caveats.md - permissions.md - python.md From d1086ee74b3abeffddaa1698d72587a1eedb10d1 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Sat, 31 Oct 2026 16:48:48 +0000 Subject: [PATCH 2/5] docs: update the migration guide for --jobs, --gen-patch-path, relative paths and install order --- docs/docs/migration.md | 43 +++++++++++++++++++++++++++--------------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/docs/docs/migration.md b/docs/docs/migration.md index e448af8e..b2956d22 100644 --- a/docs/docs/migration.md +++ b/docs/docs/migration.md @@ -11,6 +11,8 @@ [pr-review]: cli.md#-p-pr-review [gen-patch]: cli.md#-f-gen-patch [sarif-file]: cli.md#-sarif-file +[gen-patch-path]: cli.md#-gen-patch-path +[summary-output-file]: cli.md#-o-summary-output-file # Migrating from v1 @@ -18,11 +20,11 @@ This page lists what changes when moving from cpp-linter v1 (the Python package) project). Most options keep their names, short flags and meaning, so many command lines work unchanged. The sections below cover the differences. -## Removed options +## Deprecated options | v1 option | v2 behavior | What to do | |---|---|---| -| `-j`, `--jobs` | Files are always analyzed in parallel. | Remove the option. v2 exits with an "unexpected argument" error if it is given. | +| `-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 @@ -53,11 +55,15 @@ In v1, `--fix` applied clang-format fixes in place, editing the files in the wor In v2, cpp-linter never modifies the working tree. [`--gen-patch`][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. To apply the fixes locally: +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`][repo-root] folder. +[`--gen-patch-path`][gen-patch-path] (or the `GEN_PATCH_PATH` environment variable) chooses another +path and implies `--gen-patch`. To apply the fixes locally: ```shell -cpp-linter --gen-patch -git apply path/to/the/printed/patch +export GEN_PATCH_PATH=fixes.patch +cpp-linter +git apply "$GEN_PATCH_PATH" ``` ## Clang tools are installed for you @@ -67,25 +73,32 @@ v1 expects clang-format and clang-tidy to be installed already, for example with installed version to use. In v2, [`-V`, `--version`][version] also accepts a version requirement (for example `16`, `=12.0.1` -or `>=10, <13`). If no matching tools are found on the system, v2 downloads them. It tries -PyPI wheels first, then the system package manager (on by default in CI, see -[`--mod-sys`][mod-sys] and [`--no-mod-sys`][no-mod-sys]), then static binaries built by -cpp-linter. A path to an install location and a blank string (the default installed version) work +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`][mod-sys] and [`--no-mod-sys`][no-mod-sys]), then PyPI wheels, then static binaries +built by cpp-linter. A path to an install location and a blank string (the default installed version) work as in v1. Running `-V` without a value prints the cpp-linter version, like the `version` subcommand. -## Paths relative to the repository root +## Relative paths -A relative [`--database`][database] path is resolved against [`--repo-root`][repo-root] in v2. In -v1 (1.15 and later) it is resolved against the current working directory. Both give the same result -with the default `--repo-root` of `.`. If you set `--repo-root` to a sub-folder, pass the database -path relative to that folder, or use an absolute path. +In v2, a relative path given to [`--database`][database], [`--gen-patch-path`][gen-patch-path], +[`--summary-output-file`][summary-output-file] or [`--sarif-file`][sarif-file] is resolved against +the current working directory, not against [`--repo-root`][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`][sarif-file] writes clang-tidy diagnostics as a SARIF 2.1.0 file, for example to upload to GitHub code scanning. -- [`--gen-patch`][gen-patch] produces a patch of all fixes, described above. +- [`--gen-patch`][gen-patch] and [`--gen-patch-path`][gen-patch-path] produce a patch of all + fixes, described above. - [`--mod-sys`][mod-sys] and [`--no-mod-sys`][no-mod-sys] control whether system package managers may be used to install the clang tools. From fe576480e3a22b2aa9356dbb656ae83950ce0181 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Sun, 1 Nov 2026 21:16:45 +0000 Subject: [PATCH 3/5] docs: clarify review aliases, missing patches, skipped fixes and blank --version in the migration guide --- docs/docs/migration.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/docs/migration.md b/docs/docs/migration.md index b2956d22..5e181810 100644 --- a/docs/docs/migration.md +++ b/docs/docs/migration.md @@ -32,6 +32,10 @@ unchanged. The sections below cover the differences. |---|---|---| | `-d`, `--tidy-review` | [`-P`, `--pr-review`][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`][pr-review] | Same as above. `-m true` now also enables clang-tidy suggestions. | + +Because the old names are aliases of one option, a v1 command line that passes both, such as +`--tidy-review=true --format-review=false`, is rejected in v2. Replace both with a single +`--pr-review` value. | `-F`, `--fix` | [`-F`, `--gen-patch`][gen-patch] | See [Fixes are written to a patch](#fixes-are-written-to-a-patch). `--fix` is kept as an alias. | ## Changed defaults @@ -43,10 +47,11 @@ unchanged. The sections below cover the differences. Because `--lines-changed-only` is `true` by default and implies [`--files-changed-only`][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, pass: +unless told otherwise. To keep the v1 behavior of analyzing every line of every source file, +including files under `target`, pass: ```shell -cpp-linter --lines-changed-only=false --files-changed-only=false +cpp-linter --lines-changed-only=false --files-changed-only=false --ignore=.github ``` ## Fixes are written to a patch @@ -63,21 +68,26 @@ path and implies `--gen-patch`. To apply the fixes locally: ```shell export GEN_PATCH_PATH=fixes.patch cpp-linter -git apply "$GEN_PATCH_PATH" +# 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](https://github.com/cpp-linter/clang-tools-pip). `--version` only selects which installed version to use. -In v2, [`-V`, `--version`][version] also accepts a version requirement (for example `16`, `=12.0.1` -or `>=10, <13`). If no matching tools are found on the `PATH` or in the cache, v2 installs them. +In v2, [`-V`, `--version`][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`][mod-sys] and [`--no-mod-sys`][no-mod-sys]), then PyPI wheels, then static binaries -built by cpp-linter. A path to an install location and a blank string (the default installed version) work -as in v1. +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. @@ -98,7 +108,7 @@ With the default `--repo-root` of `.`, nothing changes. - [`--sarif-file`][sarif-file] writes clang-tidy diagnostics as a SARIF 2.1.0 file, for example to upload to GitHub code scanning. -- [`--gen-patch`][gen-patch] and [`--gen-patch-path`][gen-patch-path] produce a patch of all - fixes, described above. +- [`--gen-patch`][gen-patch] and [`--gen-patch-path`][gen-patch-path] produce one patch of the + clang-format and clang-tidy fixes, described above. - [`--mod-sys`][mod-sys] and [`--no-mod-sys`][no-mod-sys] control whether system package managers may be used to install the clang tools. From 47fb147abc707b4aa5faf972e80a1ac35bd0e414 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Mon, 2 Nov 2026 14:39:24 +0000 Subject: [PATCH 4/5] docs: the v1 review options can be combined since #547 --- docs/docs/migration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/migration.md b/docs/docs/migration.md index 5e181810..8539a367 100644 --- a/docs/docs/migration.md +++ b/docs/docs/migration.md @@ -33,9 +33,9 @@ unchanged. The sections below cover the differences. | `-d`, `--tidy-review` | [`-P`, `--pr-review`][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`][pr-review] | Same as above. `-m true` now also enables clang-tidy suggestions. | -Because the old names are aliases of one option, a v1 command line that passes both, such as -`--tidy-review=true --format-review=false`, is rejected in v2. Replace both with a single -`--pr-review` value. +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`. | `-F`, `--fix` | [`-F`, `--gen-patch`][gen-patch] | See [Fixes are written to a patch](#fixes-are-written-to-a-patch). `--fix` is kept as an alias. | ## Changed defaults From 9eef373aec4a59f024eff4a3201148c94053f52d Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Mon, 2 Nov 2026 14:48:45 +0000 Subject: [PATCH 5/5] docs: keep the renamed-options table in one piece --- docs/docs/migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/migration.md b/docs/docs/migration.md index 8539a367..94c5f5e3 100644 --- a/docs/docs/migration.md +++ b/docs/docs/migration.md @@ -32,11 +32,11 @@ unchanged. The sections below cover the differences. |---|---|---| | `-d`, `--tidy-review` | [`-P`, `--pr-review`][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`][pr-review] | Same as above. `-m true` now also enables clang-tidy suggestions. | +| `-F`, `--fix` | [`-F`, `--gen-patch`][gen-patch] | See [Fixes are written to a patch](#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`. -| `-F`, `--fix` | [`-F`, `--gen-patch`][gen-patch] | See [Fixes are written to a patch](#fixes-are-written-to-a-patch). `--fix` is kept as an alias. | ## Changed defaults