clang-format-action

GitHub Action for clang-format checks. Note that this Action does NOT format your code for you - it only verifies that your repository's code follows your project's formatting conventions.

You can define your own formatting rules in a .clang-format file at your repository root, or you can provide a fallback style (see fallback-style). You can also provide a path to check. If you want to run checks against multiple paths in your repository, you can use this Action in a matrix run.

Versions supported

• clang-format-3.9
• clang-format-4.0
• clang-format-5.0
• clang-format-6.0
• clang-format-7
• clang-format-8
• clang-format-9
• clang-format-10
• clang-format-11
• clang-format-12
• clang-format-13
• clang-format-14
• clang-format-15

Do you find this useful?

You can sponsor me here!

Inputs

• clang-format-version [optional]: The version of clang-format that you want to run on your codebase.
  • Default: 13
  • Available versions: see Versions supported
• check-path [optional]: The path to the directory in the repo that should be checked for C/C++/Protobuf formatting.
  • Default: .
  • For cleaner output (i.e. with no double-slashed paths), the final directory in this path should have no trailing slash, e.g. src and not src/.
• fallback-style [optional]: The fallback style for clang-format if no .clang-format file exists in your repository.
  • Default: llvm
  • Available values: LLVM, Google, Chromium, Mozilla, WebKit and others listed in the clang-format docs for BasedOnStyle.
• exclude-regex [optional]: A regex to exclude files or directories that should not be checked.
  • Default: ^$
  • Pattern matching is done with a POSIX grep -E extended regex, not a glob expression. You can exclude multiple patterns like this: (hello|world). Build and verify your regex at https://regex101.com .
• include-regex [optional]: A regex to include files or directories that should be checked.
  • Default: ^.*\.((((c|C)(c|pp|xx|\+\+)?$)|((h|H)h?(pp|xx|\+\+)?$))|(ino|pde|proto|cu))$
  • Pattern matching is done with a POSIX grep -E extended regex, not a glob expression. You can exclude multiple patterns like this: (hello|world). Build and verify your regex at https://regex101.com .

This action checks all C/C++/Protobuf (including Arduino .ino and .pde) files in the provided directory in the GitHub workspace are formatted correctly using clang-format. If no directory is provided or the provided path is not a directory in the GitHub workspace, all C/C++/Protobuf files are checked.

The following file extensions are checked by default:

• Header files:
  • .h
  • .H
  • .hpp
  • .hh
  • .h++
  • .hxx
• Source files:
  • .c
  • .C
  • .cpp
  • .cc
  • .c++
  • .cxx
  • .ino
  • .pde
  • .cu
• Protobuf files:
  • .proto

Returns:

• SUCCESS: zero exit-code if C/C++/Protobuf files in check-path are formatted correctly
• FAILURE: nonzero exit-code if C/C++/Protobuf files in check-path are not formatted correctly

Usage

⚠️This action does not run on windows GitHub Actions runners!

Single Path

To use this action, create a .github/workflows/clang-format-check.yml in your repository containing:

name: clang-format Check
on: [push, pull_request]
jobs:
  formatting-check:
    name: Formatting Check
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Run clang-format style check for C/C++/Protobuf programs.
      uses: jidicula/[email protected]
      with:
        clang-format-version: '13'
        check-path: 'src'
        fallback-style: 'Mozilla' # optional

Multiple Paths

To use this action on multiple paths in parallel, create a .github/workflows/clang-format-check.yml in your repository containing:

name: clang-format Check
on: [push, pull_request]
jobs:
  formatting-check:
    name: Formatting Check
    runs-on: ubuntu-latest
    strategy:
      matrix:
        path:
          - 'src'
          - 'examples'
    steps:
    - uses: actions/checkout@v3
    - name: Run clang-format style check for C/C++/Protobuf programs.
      uses: jidicula/[email protected]
      with:
        clang-format-version: '13'
        check-path: ${{ matrix.path }}
        fallback-style: 'Mozilla' # optional

Multiple Paths with Exclusion Regexes

To use this action on multiple paths in parallel with exclusions, create a .github/workflows/clang-format-check.yml in your repository containing:

name: clang-format Check
on: [push, pull_request]
jobs:
  formatting-check:
    name: Formatting Check
    runs-on: ubuntu-latest
    strategy:
      matrix:
        path:
          - check: 'src'
            exclude: '(hello|world)' # Exclude file paths containing "hello" or "world"
          - check: 'examples'
            exclude: ''              # Nothing to exclude
    steps:
    - uses: actions/checkout@v3
    - name: Run clang-format style check for C/C++/Protobuf programs.
      uses: jidicula/[email protected]
      with:
        clang-format-version: '13'
        check-path: ${{ matrix.path['check'] }}
        exclude-regex: ${{ matrix.path['exclude'] }}
        fallback-style: 'Mozilla' # optional

Who uses this?

These public repos use this Action.