Integrating Clang-Format and Clang-Tidy into C/C++ Workflows with Docker, Binaries, CI, and Git Hooks

This article introduces the use of LLVM's clang-format and clang-tidy (collectively called clang-tools) for C/C++ code formatting and static analysis, and discusses how to integrate these tools effectively into a development workflow.

It first describes the availability of Docker images for clang-tools, showing how to pull the image and run commands such as checking the clang-format version, formatting a source file, and diagnosing code with clang-tidy.

# 检查 clang-format 版本
$ docker run xianpengshen/clang-tools:12 clang-format --version
Ubuntu clang-format version 12.0.0-3ubuntu1~20.04.4

# 格式化代码 (helloworld.c 在仓库的 demo 目录下)
$ docker run -v $PWD:/src xianpengshen/clang-tools:12 clang-format --dry-run -i helloworld.c

# 查看 clang-tidy 版本
$ docker run xianpengshen/clang-tools:12 clang-tidy --version
LLVM (http://llvm.org/):
  LLVM version 12.0.0
  Optimized build.
  Default target: x86_64-pc-linux-gnu
  Host CPU: cascadelake

# 诊断代码 (helloworld.c 在仓库的 demo 目录下)
$ docker run -v $PWD:/src xianpengshen/clang-tools:12 clang-tidy helloworld.c \
-checks=boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-cplusplus-*,clang-analyzer-*,cppcoreguidelines-*

For environments where Docker is not preferred, the article explains how to obtain clang-tools binaries directly, either by installing the full LLVM package or by using the clang-tools-pip utility to download specific versions via pip install clang-tools . It also shows how to verify installed versions of clang-format and clang-tidy.

$ clang-format-13 --version
clang-format version 13.0.0

$ clang-tidy-13 --version
LLVM (http://llvm.org/):
  LLVM version 13.0.0
  Optimized build.
  Default target: x86_64-unknown-linux-gnu
  Host CPU: skylake

To enforce formatting and analysis in continuous integration, the guide recommends the cpp-linter-action GitHub Action. It provides a sample workflow file ( .github/workflows/cpp-linter.yml ) that runs clang-format and clang-tidy on pull requests and fails the build when issues are detected, with results shown as annotations or thread comments.

name: cpp-linter
on:
  pull_request:
    types: [opened, reopened]
  push:

jobs:
  cpp-linter:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: cpp-linter/cpp-linter-action@v1
        id: linter
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          style: file

      - name: Fail fast?!
        if: steps.linter.outputs.checks-failed > 0
        run: |
          echo "Some files failed the linting checks!"
          exit 1

For local development, the article details the use of cpp-linter-hooks via the pre-commit framework. It shows how to create a .pre-commit-config.yaml that runs clang-format and clang-tidy as git hooks, automatically fixing formatting issues and reporting static‑analysis warnings on each git commit .

repos:
- repo: https://github.com/cpp-linter/cpp-linter-hooks
  rev: v0.2.1
  hooks:
    - id: clang-format
      args: [--style=file]  # to load .clang-format
    - id: clang-tidy
      args: [--checks=.clang-tidy]  # path to .clang-tidy

Sample output from the hooks demonstrates how clang-format modifies a file and how clang-tidy reports warnings and errors, illustrating the feedback developers receive directly in the commit process.

Finally, the article advises choosing between CI‑based checks or git‑hook checks based on team preferences, noting that both can be used together, and encourages adoption of the cpp‑linter ecosystem for maintaining high C/C++ code quality.