diff --git a/docs/docs/migration.md b/docs/docs/migration.md new file mode 100644 index 00000000..94c5f5e3 --- /dev/null +++ b/docs/docs/migration.md @@ -0,0 +1,114 @@ + + +[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 +[gen-patch-path]: cli.md#-gen-patch-path +[summary-output-file]: cli.md#-o-summary-output-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. + +## 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`][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`. + +## 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, +including files under `target`, pass: + +```shell +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`][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`][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 +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](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` 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 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`][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] 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. 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