From 1e8c3dcac12c8b76041ce9c431d7bd8433717cb4 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Wed, 1 Jul 2026 14:12:14 +0200 Subject: [PATCH 1/4] docs(profile): add "Which one should I use?" channel selection table Add an orientation table that maps common workflows (CI, local pre-commit, cross-platform CLI, macOS, polyglot teams, containers, raw binaries) to the right entry point, so users can pick a channel without reading every section. Also fixes the asdf shorthand hint. --- profile/README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/profile/README.md b/profile/README.md index 6032ccc..2033a24 100644 --- a/profile/README.md +++ b/profile/README.md @@ -24,6 +24,24 @@ We target C/C++ developers and DevOps engineers who want **reliable clang toolin --- +## 🧭 Which one should I use? + +Not sure where to start? Pick the entry point that matches your workflow: + +| Your goal | Use this | How | +|-----------|----------|-----| +| Lint & format on **GitHub PRs / pushes** | [cpp-linter-action](https://github.com/cpp-linter/cpp-linter-action) | Add the action to your workflow | +| Catch issues **locally before committing** | [cpp-linter-hooks](https://github.com/cpp-linter/cpp-linter-hooks) | Add to your `.pre-commit-config.yaml` | +| Install the clang tools as a **cross-platform CLI** *(most people)* | [pip: `clang-tools`](https://github.com/cpp-linter/clang-tools-pip) | `pip install clang-tools` | +| Install on **macOS** the native way | [Homebrew tap](https://github.com/cpp-linter/homebrew-tap) | `brew tap cpp-linter/tap && brew install clang-tools` | +| Manage tool **versions across a polyglot team** | [asdf](https://github.com/cpp-linter/asdf-clang-tools) | `asdf plugin add clang-tools ` | +| Run inside **containers / custom CI images** | [clang-tools-docker](https://github.com/cpp-linter/clang-tools-docker) | Pull the image | +| Just grab the **raw static binary** | [clang-tools-static-binaries](https://github.com/cpp-linter/clang-tools-static-binaries) | Download from releases | + +> πŸ’‘ **New here?** For CI, start with **cpp-linter-action**. For local development, use **cpp-linter-hooks**. To install the underlying clang tools directly, `pip install clang-tools` works on every platform. + +--- + ## πŸš€ Get Started Integrate cpp-linter into your workflow in minutes: From 72f899b5a1563c91f7a747acb3dce8d905b87cbc Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Wed, 1 Jul 2026 15:38:13 +0200 Subject: [PATCH 2/4] docs(profile): use full asdf plugin URL in chooser table The asdf row in the "Which one should I use?" table used a placeholder, so the command was not copy/paste-runnable. Replace it with the real plugin source URL. --- profile/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/profile/README.md b/profile/README.md index 2033a24..ae87c7e 100644 --- a/profile/README.md +++ b/profile/README.md @@ -34,7 +34,7 @@ Not sure where to start? Pick the entry point that matches your workflow: | Catch issues **locally before committing** | [cpp-linter-hooks](https://github.com/cpp-linter/cpp-linter-hooks) | Add to your `.pre-commit-config.yaml` | | Install the clang tools as a **cross-platform CLI** *(most people)* | [pip: `clang-tools`](https://github.com/cpp-linter/clang-tools-pip) | `pip install clang-tools` | | Install on **macOS** the native way | [Homebrew tap](https://github.com/cpp-linter/homebrew-tap) | `brew tap cpp-linter/tap && brew install clang-tools` | -| Manage tool **versions across a polyglot team** | [asdf](https://github.com/cpp-linter/asdf-clang-tools) | `asdf plugin add clang-tools ` | +| Manage tool **versions across a polyglot team** | [asdf](https://github.com/cpp-linter/asdf-clang-tools) | `asdf plugin add clang-tools https://github.com/cpp-linter/asdf-clang-tools` | | Run inside **containers / custom CI images** | [clang-tools-docker](https://github.com/cpp-linter/clang-tools-docker) | Pull the image | | Just grab the **raw static binary** | [clang-tools-static-binaries](https://github.com/cpp-linter/clang-tools-static-binaries) | Download from releases | From d41e5dfde670ef1ab371f2b5c5599864ab3423d0 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Wed, 1 Jul 2026 15:41:04 +0200 Subject: [PATCH 3/4] docs(profile): restructure README to cut section overlap Merge the overlapping "Get Started", "Clang Tools" and "Easy Installation" sections into a single "All projects" reference table so each repo is described once. Keep the chooser table as the primary "by goal" navigation, add a minimal cpp-linter-action usage example, and note LLVM/platform coverage in the About blurb. --- profile/README.md | 59 ++++++++++++++++++++++++++++++----------------- 1 file changed, 38 insertions(+), 21 deletions(-) diff --git a/profile/README.md b/profile/README.md index ae87c7e..16bb84e 100644 --- a/profile/README.md +++ b/profile/README.md @@ -20,7 +20,7 @@ **cpp-linter** bundles the power of `clang-format`, `clang-tidy`, and other LLVM tools into packages that are easy to install, integrate, and maintain. Whether you’re linting a single file locally or enforcing code quality across dozens of repos in CI, cpp-linter has you covered. -We target C/C++ developers and DevOps engineers who want **reliable clang tooling without the build-from-source headache**. +We target C/C++ developers and DevOps engineers who want **reliable clang tooling without the build-from-source headache**. Our packages track the latest LLVM releases and cover Linux, macOS, and Windows on both x86_64 and Arm. --- @@ -42,36 +42,53 @@ Not sure where to start? Pick the entry point that matches your workflow: --- -## πŸš€ Get Started +## ⚑ Quick example -Integrate cpp-linter into your workflow in minutes: +Lint every pull request with **cpp-linter-action** β€” no local setup required: -- **[cpp-linter-action](https://github.com/cpp-linter/cpp-linter-action)** β€” GitHub Action that runs `clang-format` and `clang-tidy` on PRs and pushes, posting inline annotations. -- **[cpp-linter-hooks](https://github.com/cpp-linter/cpp-linter-hooks)** β€” [pre-commit](https://pre-commit.com/) hooks for local development β€” catch issues before they hit CI. +```yaml +# .github/workflows/cpp-linter.yml +name: cpp-linter +on: pull_request ---- +jobs: + cpp-linter: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: cpp-linter/cpp-linter-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + style: file # format against your .clang-format + tidy-checks: '' # analyze against your .clang-tidy +``` -## πŸ”§ Clang Tools β€” Simplified +The action posts inline annotations, a step summary, and (optionally) PR review suggestions. See the [cpp-linter-action](https://github.com/cpp-linter/cpp-linter-action) docs for all inputs and outputs. -We provide ready-to-use **binaries**, **Docker images**, and **Python wheels** of key clang tools: +--- -| Package | Description | -|---------|-------------| -| [clang-tools-static-binaries](https://github.com/cpp-linter/clang-tools-static-binaries) | Statically-linked `clang-format`, `clang-tidy`, `clang-query`, `clang-apply-replacements`, and `clang-include-cleaner` binaries | -| [clang-tools-docker](https://github.com/cpp-linter/clang-tools-docker) | Docker images with pre-installed `clang-format` and `clang-tidy` | -| [clang-tools-wheel](https://github.com/cpp-linter/clang-tools-wheel) | Redistribute `clang-format` and `clang-tidy` Python wheels | -| [clang-apply-replacements](https://github.com/cpp-linter/clang-apply-replacements) | Standalone Python wheel for `clang-apply-replacements` | -| [clang-include-cleaner](https://github.com/cpp-linter/clang-include-cleaner) | Standalone Python wheel for `clang-include-cleaner` β€” detects unused `#include` directives | +## πŸ“š All projects ---- +**Integrations** -## πŸ“¦ Easy Installation +| Project | What it does | +|---------|--------------| +| [cpp-linter-action](https://github.com/cpp-linter/cpp-linter-action) | GitHub Action that runs `clang-format` and `clang-tidy` on PRs and pushes, posting inline annotations, thread comments, step summaries, and PR reviews. | +| [cpp-linter-hooks](https://github.com/cpp-linter/cpp-linter-hooks) | [pre-commit](https://pre-commit.com/) hooks that run `clang-format` and `clang-tidy` locally β€” catch issues before they reach CI. | -Prefer modern package managers? Install `clang-format`, `clang-tidy`, `clang-query`, and more via: +**Clang tool distributions** -- **[pip](https://github.com/cpp-linter/clang-tools-pip)** β€” `pip install clang-tools` β€” installs static binaries or Python wheels for `clang-format`, `clang-tidy`, `clang-query`, `clang-apply-replacements`, and `clang-include-cleaner` -- **[asdf](https://github.com/cpp-linter/asdf-clang-tools)** β€” `asdf plugin add clang-tools https://github.com/cpp-linter/asdf-clang-tools` -- **[Homebrew Tap](https://github.com/cpp-linter/homebrew-tap)** β€” `brew tap cpp-linter/tap && brew install clang-tools` β€” installs pre-built static binaries for `clang-format`, `clang-tidy`, `clang-query`, `clang-apply-replacements`, and `clang-include-cleaner` +| Project | What it does | +|---------|--------------| +| [clang-tools-pip](https://github.com/cpp-linter/clang-tools-pip) | `pip install clang-tools` β€” cross-platform CLI that installs `clang-format`, `clang-tidy`, `clang-query`, `clang-apply-replacements`, and `clang-include-cleaner` (static binaries or Python wheels). | +| [homebrew-tap](https://github.com/cpp-linter/homebrew-tap) | Homebrew formulae for the clang tools on macOS. | +| [asdf-clang-tools](https://github.com/cpp-linter/asdf-clang-tools) | [asdf](https://asdf-vm.com/) plugin for version-managed installs across a team. | +| [clang-tools-docker](https://github.com/cpp-linter/clang-tools-docker) | Docker images with `clang-format` and `clang-tidy` pre-installed for CI. | +| [clang-tools-static-binaries](https://github.com/cpp-linter/clang-tools-static-binaries) | The upstream source: statically-linked binaries for Linux, macOS, and Windows that every other distribution builds on. | +| [clang-tools-wheel](https://github.com/cpp-linter/clang-tools-wheel) | Python wheels that redistribute `clang-format` and `clang-tidy`. | +| [clang-apply-replacements](https://github.com/cpp-linter/clang-apply-replacements) | Standalone Python wheel for `clang-apply-replacements`. | +| [clang-include-cleaner](https://github.com/cpp-linter/clang-include-cleaner) | Standalone Python wheel for `clang-include-cleaner` β€” detects unused `#include` directives. | --- From 9008ab0c35b2768117b34f4468e8c441c78965cb Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Wed, 1 Jul 2026 15:49:01 +0200 Subject: [PATCH 4/4] docs(profile): slim README to a single chooser + collapsed extras Drop the flat "All projects" table that re-listed the same repos as the chooser (~70% overlap). Keep the chooser as the only primary navigation and the quick example, and move the lower-level/specialized packages into a collapsed "More packages" section so the front page leads with the handful of entry points most people actually need. --- profile/README.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/profile/README.md b/profile/README.md index 16bb84e..8b609c0 100644 --- a/profile/README.md +++ b/profile/README.md @@ -66,30 +66,24 @@ jobs: The action posts inline annotations, a step summary, and (optionally) PR review suggestions. See the [cpp-linter-action](https://github.com/cpp-linter/cpp-linter-action) docs for all inputs and outputs. ---- +
+πŸ“¦ More packages β€” lower-level & specialized builds -## πŸ“š All projects +
-**Integrations** +The tools above are built on a few underlying distributions you can also use directly: | Project | What it does | |---------|--------------| -| [cpp-linter-action](https://github.com/cpp-linter/cpp-linter-action) | GitHub Action that runs `clang-format` and `clang-tidy` on PRs and pushes, posting inline annotations, thread comments, step summaries, and PR reviews. | -| [cpp-linter-hooks](https://github.com/cpp-linter/cpp-linter-hooks) | [pre-commit](https://pre-commit.com/) hooks that run `clang-format` and `clang-tidy` locally β€” catch issues before they reach CI. | - -**Clang tool distributions** - -| Project | What it does | -|---------|--------------| -| [clang-tools-pip](https://github.com/cpp-linter/clang-tools-pip) | `pip install clang-tools` β€” cross-platform CLI that installs `clang-format`, `clang-tidy`, `clang-query`, `clang-apply-replacements`, and `clang-include-cleaner` (static binaries or Python wheels). | -| [homebrew-tap](https://github.com/cpp-linter/homebrew-tap) | Homebrew formulae for the clang tools on macOS. | -| [asdf-clang-tools](https://github.com/cpp-linter/asdf-clang-tools) | [asdf](https://asdf-vm.com/) plugin for version-managed installs across a team. | -| [clang-tools-docker](https://github.com/cpp-linter/clang-tools-docker) | Docker images with `clang-format` and `clang-tidy` pre-installed for CI. | | [clang-tools-static-binaries](https://github.com/cpp-linter/clang-tools-static-binaries) | The upstream source: statically-linked binaries for Linux, macOS, and Windows that every other distribution builds on. | | [clang-tools-wheel](https://github.com/cpp-linter/clang-tools-wheel) | Python wheels that redistribute `clang-format` and `clang-tidy`. | | [clang-apply-replacements](https://github.com/cpp-linter/clang-apply-replacements) | Standalone Python wheel for `clang-apply-replacements`. | | [clang-include-cleaner](https://github.com/cpp-linter/clang-include-cleaner) | Standalone Python wheel for `clang-include-cleaner` β€” detects unused `#include` directives. | +Browse every repository on the [organization page](https://github.com/cpp-linter). + +
+ --- ## πŸ‘₯ Maintainers