Clang‐format

This page contains some notes for working with clang-format.

clang-format configuration

Clang-format has a large number of options to tune the formatting: https://clang.llvm.org/docs/ClangFormatStyleOptions.html

The clang format configuration file for the MueLu package can be found at https://github.com/trilinos/Trilinos/blob/master/packages/muelu/.clang-format .

clang-format github action

PRs that contain code changes to packages/muelu/ are checked using the action at https://github.com/trilinos/Trilinos/blob/master/.github/workflows/muelu_clang_format.yml

git pre-commit hooks

https://pre-commit.com allows to run clang-format locally. Create a file .pre-commit-config.yaml in the root of the Trilinos source tree:

files: "packages/(muelu|tempus)/.*pp"
exclude: "packages/tempus/examples/.*"
repos:
-   repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v14.0.1
    hooks:
    - id: clang-format
      types_or: [c++, c, cuda]

Then install pre-commit via

python3 -m pip install pre-commit
pre-commit install

On Mac one can also install pre-commit via

brew install pre-commit

NOTE: Please do not commit the file .pre-commit-config.yaml.

Ignoring large commits

The first run of clang-format can make a lot of changes. In order to not spoil git-blame we maintain a list of these commits in .git-blame-ignore-revs. In order to configure git to ignore them, simply do:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Enabling clang-format for a new package

1. Create a configuration file .clang-format under packages/myPackage. See https://github.com/trilinos/Trilinos/blob/master/packages/muelu/.clang-format for an example.
2. Run clang-format for the first time. Please make sure you are using a clang-format version 14 as the output can differ between versions. One simple way to achieve this is to use pre-commit via pre-commit run --all-files. Just make sure that packages/myPackage is listed in the pre-commit configuration.
3. Commit the changes (the new .clang-format and the code changes; do not commit .pre-commit-config.yaml).
4. Add the SHA for the previous commit to https://github.com/trilinos/Trilinos/blob/master/.git-blame-ignore-revs so that the formatting changes are ignored by git-blame.
5. Add ./packages/myPackage to the source field in https://github.com/trilinos/Trilinos/blob/master/.github/workflows/muelu_clang_format.yml