From 9ad7d53d237b29f6f63c95245b25c2374f2d7e31 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 23 Oct 2026 08:23:52 +0000 Subject: [PATCH 1/2] docs: use v1.8.0 and recommend additional_dependencies Point the README and examples at v1.8.0. Recommend pinning the clang tool wheel in additional_dependencies, so pre-commit installs it once with the hook, as mirrors-clang-format does, and note that parallel hook runs install the wheel once. --- README.md | 43 +++++++++++++++++++++++++--------------- examples/cmake/README.md | 2 +- examples/meson/README.md | 2 +- 3 files changed, 29 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 788b59e..5d363a5 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Add this configuration to your `.pre-commit-config.yaml` file: ```yaml repos: - repo: https://github.com/cpp-linter/cpp-linter-hooks - rev: v1.7.0 + rev: v1.8.0 hooks: - id: clang-format args: [--style=file, --version=21] @@ -35,12 +35,16 @@ a `compile_commands.json`, which it looks for in `build/` and a few other direct it skips clang-tidy on your machine and fails in CI (see [Compilation database](https://github.com/cpp-linter/cpp-linter-hooks#compilation-database)). +For teams, CI and machines behind a firewall or a company PyPI mirror, also pin the wheel in +`additional_dependencies` so pre-commit installs it once, with the hook (see +[Install the tool with the hook](https://github.com/cpp-linter/cpp-linter-hooks#install-the-tool-with-the-hook)). + ## Usage ### Custom clang tool version > [!TIP] -> The `rev` tag (e.g. `v1.7.0`) is the **project** version, not the clang tool version. Without +> The `rev` tag (e.g. `v1.8.0`) is the **project** version, not the clang tool version. Without > `--version`, each hook installs the newest clang-format or clang-tidy wheel on PyPI the first time > it runs and keeps it until pre-commit rebuilds the hook environment, so two machines can run > different LLVM versions with the same configuration. For production use, always pin the tool @@ -53,12 +57,14 @@ it skips clang-tidy on your machine and fails in CI (see a wheel, the hook fails and lists some of the versions that exist. - When the hook environment already has a wheel that matches `--version` (or any wheel, without `--version`), the hook uses it and does not contact pypi.org. Otherwise it looks the version up - on pypi.org and installs it, so that run needs network access. + on pypi.org and installs it, so that run needs network access. pre-commit runs the hook on + groups of files in parallel; one of them installs the wheel and the others wait for it. -### Offline and pre-commit.ci +### Install the tool with the hook -To install the clang tool together with the hook, list the exact wheel in -`additional_dependencies`: +We recommend listing the exact wheel in `additional_dependencies`. pre-commit then installs the +clang tool once, when it creates the hook environment, the same way +[mirrors-clang-format](https://github.com/pre-commit/mirrors-clang-format) does: ```yaml - id: clang-format @@ -69,11 +75,16 @@ To install the clang tool together with the hook, list the exact wheel in additional_dependencies: [clang-tidy==21.1.6] ``` -pre-commit installs `additional_dependencies` when it creates the hook environment (for example -with `pre-commit install-hooks`), so the hooks need no network access when they run. Use this on -[pre-commit.ci](https://pre-commit.ci/), which runs hooks without network access, and behind a -firewall. The pinned wheel must match `--version`; otherwise the hook installs the `--version` one -at run time. +pre-commit installs `additional_dependencies` with the hook (for example on +`pre-commit install-hooks`), through the same package index it uses for the hook itself. The hooks +then never install anything or contact pypi.org when they run, so this works: + +- on [pre-commit.ci](https://pre-commit.ci/), which runs hooks without network access, +- behind a firewall or with a company PyPI mirror, where pypi.org may be blocked or slow, +- for teams and CI, where every machine gets exactly the same wheel. + +The pinned wheel must match `--version`; otherwise the hook installs the `--version` one at run +time. Without `--version`, the hook uses the pinned wheel. ### clang-format @@ -204,7 +215,7 @@ See [Performance optimization](https://github.com/cpp-linter/cpp-linter-hooks#pe ```yaml repos: - repo: https://github.com/cpp-linter/cpp-linter-hooks - rev: v1.7.0 # includes --fix support + rev: v1.8.0 # includes --fix support hooks: - id: clang-tidy args: [--fix] @@ -227,7 +238,7 @@ repository root works too. ```yaml repos: - repo: https://github.com/cpp-linter/cpp-linter-hooks - rev: v1.7.0 + rev: v1.8.0 hooks: - id: clang-tidy # Auto-detects ./build/compile_commands.json if present @@ -282,7 +293,7 @@ Three self-contained templates plus quick snippets for other common setups. ```yaml - repo: https://github.com/cpp-linter/cpp-linter-hooks - rev: v1.7.0 + rev: v1.8.0 hooks: - id: clang-format args: [--style=file, --version=21] @@ -297,7 +308,7 @@ or `-j`: ```yaml - repo: https://github.com/cpp-linter/cpp-linter-hooks - rev: v1.7.0 + rev: v1.8.0 hooks: - id: clang-tidy args: [--version=21, --jobs=4] @@ -334,7 +345,7 @@ This approach ensures that only modified files are checked, further speeding up ```yaml repos: - repo: https://github.com/cpp-linter/cpp-linter-hooks - rev: v1.7.0 + rev: v1.8.0 hooks: - id: clang-format args: [--style=file, --version=21, --verbose] # Shows processed files diff --git a/examples/cmake/README.md b/examples/cmake/README.md index b929f56..adf80d5 100644 --- a/examples/cmake/README.md +++ b/examples/cmake/README.md @@ -7,7 +7,7 @@ If you already have a CMake project, you need **two files**: ```yaml repos: - repo: https://github.com/cpp-linter/cpp-linter-hooks - rev: v1.7.0 + rev: v1.8.0 hooks: - id: clang-format args: [--style=file, --version=21] diff --git a/examples/meson/README.md b/examples/meson/README.md index 51e4d97..b0795e4 100644 --- a/examples/meson/README.md +++ b/examples/meson/README.md @@ -7,7 +7,7 @@ If you already have a Meson project, configure the hooks and generate a compilat ```yaml repos: - repo: https://github.com/cpp-linter/cpp-linter-hooks - rev: v1.7.0 + rev: v1.8.0 hooks: - id: clang-format args: [--style=file, --version=21] From c7694c9f109395556533f3bd8ca2161d30124fe1 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen <3353385+shenxianpeng@users.noreply.github.com> Date: Fri, 23 Oct 2026 08:25:30 +0000 Subject: [PATCH 2/2] chore: drop the outdated default-version note from release notes The note said the hook always uses the latest clang tool release. Since #302 an installed wheel is reused and not upgraded, so the note was wrong. Without the note the workflow can call the shared org release-drafter workflow, like the other cpp-linter repos. --- .github/workflows/release-drafter.yml | 42 +++------------------------ 1 file changed, 4 insertions(+), 38 deletions(-) diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml index 2d571ac..c1dd3ae 100644 --- a/.github/workflows/release-drafter.yml +++ b/.github/workflows/release-drafter.yml @@ -6,45 +6,11 @@ on: - "main" workflow_dispatch: +permissions: {} + jobs: draft-release: permissions: - # write permission is required to create a github release contents: write - # write permission is required for autolabeler - # otherwise, read permission is required at least - pull-requests: write - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - - name: Generate release notes header - run: | - { - echo "## 💡 Default Clang Tool Versions" - echo "" - echo "Versions are resolved dynamically from PyPI at hook runtime, always using the latest stable release by default. " - echo "You can pin a specific version by adding the \`--version\` argument under \`args\` in your pre-commit config." - echo "See [Custom Clang Tool Version](https://github.com/cpp-linter/cpp-linter-hooks?tab=readme-ov-file#custom-clang-tool-version) for details." - echo "" - } > release_notes.md - cat release_notes.md - - # Export release notes content to env variable for Release Drafter - { - echo "RELEASE_BODY<> "$GITHUB_ENV" - - # Draft your next Release notes as Pull Requests are merged into the default branch - - uses: release-drafter/release-drafter@978bb0b30c5ee8cdd332ced253758157150d43f0 # v7.10.0 - with: - commitish: 'main' - header: ${{ env.RELEASE_BODY }} - config-name: github:cpp-linter/.github:/.github/release-drafter.yml - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + pull-requests: read + uses: cpp-linter/.github/.github/workflows/release-drafter.yml@main