add precommit as an easier user entry point for clangformat

.github/workflows/prechecks.yml

@@ -14,21 +14,28 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
       - name: Add LLVM apt repo (Clang 19)
         run: |
           wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
           sudo add-apt-repository "deb http://apt.llvm.org/jammy/ llvm-toolchain-jammy-19 main"
           sudo apt-get update
 
-      - name: Install clang-format
+      - name: Install formatting tools
         run: |
           sudo apt-get install -y clang-format-19
+          python -m pip install --upgrade pip
+          python -m pip install pre-commit
+          pre-commit --version
           clang-format-19 --version
 
-      - name: Check formatting
+      - name: Run pre-commit
         run: |
-          FILES=$(git ls-files '*.cpp' '*.h' '*.cu' '*.cuh' '*.hh' '*.cc' '*.icc')
-          clang-format-19 -style=file -n --Werror $FILES
+          pre-commit run --all-files --show-diff-on-failure --color=always
 
   docs-build:
     name: Docs

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2026 CERN
+# SPDX-License-Identifier: Apache-2.0
+
+repos:
+  - repo: local
+    hooks:
+      - id: clang-format
+        name: clang-format-19
+        entry: ./tools/clang-format-pre-commit.sh
+        language: system
+        files: \.(cc|cpp|cu|cuh|h|hh|icc)$

CONTRIBUTING.md

@@ -89,17 +89,31 @@ Make sure that the documentation is still valid after your changes. Perform upda
 
 #### C++
 
-The AdePT project uses [clang-format](http://clang.llvm.org/docs/ClangFormat.html) for formatting its C++ source code. A `.clang-format` configuration file comes with the project and should be used to automatically format the code. Developers can use the **FIXME** provided Docker image to format their project or install `clang-format` locally.
-Developers should be aware that clang-format will behave differently for different versions, so should prefer the same version as recommended for
-AdePT, which is 9. There are several instructions available on how to integrate clang-format with your favourite IDE (e.g. [eclipse](https://marketplace.eclipse.org/content/cppstyle), [Xcode](https://github.com/travisjeffery/ClangFormat-Xcode), [emacs](http://clang.llvm.org/docs/ClangFormat.html#emacs-integration)). It can also be integrated with git
-via the [`git-clang-format`](https://github.com/llvm-mirror/clang/blob/master/tools/clang-format/git-clang-format) Python 2/3 script supplied by installs of `clang-format` (or simply copy it to your `PATH` and make it executable). It may be used to check and apply formatting to files changed
+The AdePT project uses [clang-format](http://clang.llvm.org/docs/ClangFormat.html) for formatting its C++ source code. A `.clang-format` configuration file and a `.pre-commit-config.yaml` hook definition come with the project and should be used to automatically format the code.
+
+Install `pre-commit` and `clang-format-19`, then enable the hook locally:
+
+```console
+$ pre-commit install
+```
+
+To reformat all tracked source files manually, run:
+
+```console
+$ pre-commit run --all-files
+```
+
+AdePT requires clang-format version 19. Older versions do not produce compatible formatting and will fail CI. On some systems the executable is named `clang-format-19`; on others it is `clang-format` but still reports version 19.
+
+There are several instructions available on how to integrate clang-format with your favourite IDE (e.g. [eclipse](https://marketplace.eclipse.org/content/cppstyle), [Xcode](https://github.com/travisjeffery/ClangFormat-Xcode), [emacs](http://clang.llvm.org/docs/ClangFormat.html#emacs-integration)). It can also be integrated with git
+via the [`git-clang-format`](https://github.com/llvm-mirror/clang/blob/master/tools/clang-format/git-clang-format) Python 2/3 script supplied by installs of `clang-format` (or simply copy it to your `PATH` and make it executable). It may still be used to reformat only the files changed
 in 1-N commits, e.g. to apply formatting to files changed in the last commit:
 
 ```console
 $ git clang-format HEAD~1
 ```
 
-Run `git clang-format -h` for further options. The AdePT CI system will **FIXME** automatically check code reformatting using the provided clang-format configuration on pull requests. However, developers are encouraged to use code formating locally to reduce conflicts due to formatting issues.
+Run `git clang-format -h` for further options. The AdePT CI system runs `pre-commit` on pull requests and pushes, using the same clang-format 19 configuration that developers are expected to run locally.
 
 In addition, some conventions are used in AdePT code. For Doxygen documentation, please follow these recommendations:
 

tools/clang-format-pre-commit.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+# SPDX-FileCopyrightText: 2026 CERN
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+  exit 0
+fi
+
+if command -v clang-format-19 >/dev/null 2>&1; then
+  exec clang-format-19 -style=file -i "$@"
+fi
+
+if command -v clang-format >/dev/null 2>&1; then
+  version_output=$(clang-format --version || true)
+  if printf '%s\n' "${version_output}" | grep -Eq 'version 19([.][0-9]+)*([[:space:]]|$)'; then
+    exec clang-format -style=file -i "$@"
+  fi
+fi
+
+printf '%s\n' "clang-format 19 is required. Install clang-format-19 or provide clang-format version 19 on PATH." >&2
+exit 1