cpp-linter-hooks

pre-commit hooks that pip-install the clang-format and clang-tidy version you pin, on every developer's machine.

Website · Get started · Discussions

Quick start

Add this configuration to your .pre-commit-config.yaml file:

repos:
  - repo: https://github.com/cpp-linter/cpp-linter-hooks
    rev: v1.6.1
    hooks:
      - id: clang-format
        args: [--style=file, --version=21]
      - id: clang-tidy
        args: [--version=21]

Run pre-commit install once in each clone. --style=file loads the style from your .clang-format file, and clang-tidy reads your .clang-tidy file by itself. The clang-tidy hook needs a compile_commands.json, which it looks for in build/ and a few other directories (see Compilation database); leave it out if you only run clang-tidy in CI, for example with cpp-linter-action.

Usage

Custom clang tool version

• --version=21 installs the newest 21.x wheel, and --version=21.1.8 pins an exact release. clang-tidy wheels are released separately from clang-format wheels and skip some releases, so give clang-tidy the major version.
• clang-format wheels cover LLVM 6 to 23 and clang-tidy wheels LLVM 13 to 23. For a version without 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.

Offline and pre-commit.ci

To install the clang tool together with the hook, list the exact wheel in additional_dependencies:

      - id: clang-format
        args: [--style=file, --version=21]
        additional_dependencies: [clang-format==21.1.8]
      - id: clang-tidy
        args: [--version=21]
        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, 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.

clang-format

To use a predefined coding style instead of your .clang-format file:

      - id: clang-format
        args: [--style=Google] # Other coding style: LLVM, GNU, Chromium, Microsoft, Mozilla, WebKit.

When clang-format changes a file, the hook fails and pre-commit stops the commit:

clang-format.............................................................Failed
- hook id: clang-format
- files were modified by this hook

Here’s a sample diff showing the formatting applied with --style=Google:

--- a/testing/main.c
+++ b/testing/main.c
@@ -1,3 +1,6 @@
 #include <stdio.h>
-int main() {for (;;) break; printf("Hello world!\n");return 0;}
-
+int main() {
+  for (;;) break;
+  printf("Hello world!\n");
+  return 0;
+}

clang-format.............................................................Failed
- hook id: clang-format
- exit code: 1

main.c:2:13: error: code should be clang-formatted [-Wclang-format-violations]
int main() {for (;;) break; printf("Hello world!\n");return 0;}
            ^
main.c:2:21: error: code should be clang-formatted [-Wclang-format-violations]
int main() {for (;;) break; printf("Hello world!\n");return 0;}
                    ^
main.c:2:28: error: code should be clang-formatted [-Wclang-format-violations]
int main() {for (;;) break; printf("Hello world!\n");return 0;}
                           ^
main.c:2:54: error: code should be clang-formatted [-Wclang-format-violations]
int main() {for (;;) break; printf("Hello world!\n");return 0;}
                                                     ^
main.c:2:63: error: code should be clang-formatted [-Wclang-format-violations]
int main() {for (;;) break; printf("Hello world!\n");return 0;}
                                                              ^

clang-tidy

To set the checks in args instead of your .clang-tidy file, quote the whole option: inside [...], YAML splits an unquoted value at each comma. When that happens, the hook joins the pieces again and adds a note on how to fix the configuration. --checks takes check names, not a file: clang-tidy reads the nearest .clang-tidy file by itself, so --checks=.clang-tidy does nothing.

      - id: clang-tidy
        args: ["--checks=boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*"]

When clang-tidy reports a warning or an error, the hook fails:

clang-tidy...............................................................Failed
- hook id: clang-tidy
- exit code: 1

/home/runner/work/cpp-linter-hooks/cpp-linter-hooks/testing/main.c:4:13: warning: statement should be inside braces [readability-braces-around-statements]
    for (;;)
            ^
             {

The hook passes -quiet to clang-tidy and drops status lines such as 522 warnings generated., which count warnings in system headers that clang-tidy does not show. Add --verbose to args to keep clang-tidy's full output.

repos:
  - repo: https://github.com/cpp-linter/cpp-linter-hooks
    rev: v1.6.1  # includes --fix support
    hooks:
      - id: clang-tidy
        args: [--fix]

Compilation database

For CMake or Meson projects, clang-tidy works best with a compile_commands.json file that records the exact compiler flags used for each file. Without it, clang-tidy may report false positives from missing include paths or wrong compiler flags.

The hook auto-detects compile_commands.json in common build directories (build/, out/, cmake-build-debug/, _build/) and passes -p <dir> to clang-tidy automatically — no configuration needed for most projects:

repos:
  - repo: https://github.com/cpp-linter/cpp-linter-hooks
    rev: v1.6.1
    hooks:
      - id: clang-tidy
        # Auto-detects ./build/compile_commands.json if present

To specify the build directory explicitly:

      - id: clang-tidy
        args: [--compile-commands=build]

To disable auto-detection (e.g. in a monorepo where auto-detect might pick the wrong database):

      - id: clang-tidy
        args: [--no-compile-commands]

Examples

Three self-contained templates plus quick snippets for other common setups.

• CMake minimal config
• Meson minimal config
• Large project files: regex — scoping hooks for speed
• Quick snippets — Meson, clang-format-only, monorepo, CI, compile_commands.json

Troubleshooting

Performance optimization

- repo: https://github.com/cpp-linter/cpp-linter-hooks
  rev: v1.6.1
  hooks:
    - id: clang-format
      args: [--style=file, --version=21]
      files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$ # Limits to specific dirs and file types
    - id: clang-tidy
      args: [--version=21]
      files: ^(src|include)/.*\.(cpp|cc|cxx|h|hpp)$

For clang-tidy, you can also process multiple files in parallel by adding --jobs or -j:

- repo: https://github.com/cpp-linter/cpp-linter-hooks
  rev: v1.6.1
  hooks:
    - id: clang-tidy
      args: [--version=21, --jobs=4]

Alternatively, if you want to run the hooks manually on only the changed files, you can use the following command:

pre-commit run --files $(git diff --name-only)

This approach ensures that only modified files are checked, further speeding up the linting process during development.

Verbose output

repos:
  - repo: https://github.com/cpp-linter/cpp-linter-hooks
    rev: v1.6.1
    hooks:
      - id: clang-format
        args: [--style=file, --version=21, --verbose]   # Shows processed files
      - id: clang-tidy
        args: [--verbose]   # Shows which compile_commands.json is used

Compared with mirrors-clang-format

mirrors-clang-format is pre-commit's mirror of the clang-format wheel.

Used by

These organizations run cpp-linter-hooks on their default branch:

MIT ACL · Bazel Contrib · CodSpeed · doldecomp · HKUST Aerial Robotics · Kubewarden · Computational Geography · IMSY · CONVINCE-Project

The showcase lists more projects that use cpp-linter tools.

Sponsors

cpp-linter is maintained by two volunteers. Sponsor the project through Open Collective. Silver and Gold sponsors get their logo here.

Contributing

See the contributing guide and open an issue for bugs and feature requests.

License

This project is licensed under the MIT License.