Skip to content

A Github Action for linting C/C++ code integrating clang-tidy and clang-format to collect feedback provided in the form of file-annotations, thread-comments, workflow step-summary, and Pull Request reviews.

License

Notifications You must be signed in to change notification settings

cpp-linter/cpp-linter-action

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

C/C++ Lint Action | clang-format & clang-tidy

GitHub release (latest SemVer) GitHub marketplace GitHub Workflow Status GitHub Workflow Status GitHub

A Github Action for linting C/C++ code integrating clang-tidy and clang-format to collect feedback provided in the form of thread comments and/or annotations.

Usage

Create a new GitHub Actions workflow in your project, e.g. at .github/workflows/cpp-linter.yml

The content of the file should be in the following format.

# Workflow syntax:
# https://help.github.com/en/articles/workflow-syntax-for-github-actions
name: cpp-linter

on:
  pull_request:
    types: [opened, reopened]  # let PR-synchronize events be handled by push events
  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!"
        # for actual deployment
        # run: exit 1

Optional Inputs

style

  • Description: The style rules to use.
    • Set this to 'file' to have clang-format use the closest relative .clang-format file.
    • Set this to a blank string ('') to disable the use of clang-format entirely.
  • Default: 'llvm'

extensions

  • Description: The file extensions to run the action against. This is a comma-separated string.
  • Default: 'c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx'

tidy-checks

  • Description: Comma-separated list of globs with optional - prefix. Globs are processed in order of appearance in the list. Globs without - prefix add checks with matching names to the set, globs with the - prefix remove checks with matching names from the set of enabled checks. This option's value is appended to the value of the 'Checks' option in a .clang-tidy file (if any).
    • It is possible to disable clang-tidy entirely by setting this option to '-*'.
    • It is also possible to rely solely on a .clang-tidy config file by specifying this option as a blank string ('').
  • Default: 'boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*'

repo-root

  • Description: The relative path to the repository root directory. This path is relative to the path designated as the runner's GITHUB_WORKSPACE environment variable.
  • Default: '.'

version

  • Description: The desired version of the clang-tools to use. Accepted options are strings which can be 14, 13, 12, 11, 10, 9, or 8.
    • Set this option to a blank string ('') to use the platform's default installed version.
    • This value can also be a path to where the clang tools are installed (if using a custom install location). Because all paths specified here are converted to absolute, using a relative path as a value may not be compatible when using the docker environment (see Running without the docker container).
  • Default: '12'

verbosity

  • Description: This controls the action's verbosity in the workflow's logs. Supported options are defined by the python logging library's log levels. This option does not affect the verbosity of resulting thread comments or file annotations.
  • Default: '10'

lines-changed-only

  • Description: This controls what part of the files are analyzed. The following values are accepted:
    • false: All lines in a file are analyzed.
    • true: Only lines in the diff that contain additions are analyzed.
    • diff: All lines in the diff are analyzed (including unchanged lines but not subtractions).
  • Default: false.

files-changed-only

  • Description: Set this option to false to analyze any source files in the repo. This is automatically enabled if lines-changed-only is enabled.
  • Default: true
  • NOTE: The GITHUB_TOKEN should be supplied when running on a private repository with this option enabled, otherwise the runner does not not have the privilege to list changed files for an event. See Authenticating with the GITHUB_TOKEN

ignore

  • Description: Set this option with string of path(s) to ignore.
    • In the case of multiple paths, you can use a pipe character (|) to separate the multiple paths. Multiple lines are forbidden as an input to this option; it must be a single string.
    • This can also have files, but the file's relative path has to be specified as well.
    • There is no need to use ./ for each entry; a blank string ('') represents the repo-root path (specified by the repo-root input option).
    • Submodules are automatically ignored. Hidden directories (beginning with a .) are also ignored automatically.
    • Prefix a path with a bang (!) to make it explicitly not ignored. The order of multiple paths does not take precedence. The ! prefix can be applied to a submodule's path (if desired) but not hidden directories.
    • Glob patterns are not supported here. All asterisk characters (*) are literal.
  • Default: '.github'

thread-comments

  • Description: Set this option to false to disable the use of thread comments as feedback.
  • Default: false
  • NOTE: If run on a private repository, then this feature is disabled because the GitHub REST API behaves differently for thread comments on a private repository.

file-annotations

  • Description: Set this option to false to disable the use of file annotations as feedback.
  • Default: true

database

  • Description: The directory containing compilation database (like compile_commands.json) file.
  • Default: ''

Outputs

This action creates 1 output variable named checks-failed. Even if the linting checks fail for source files this action will still pass, but users' CI workflows can use this action's output to exit the workflow early if that is desired.

Running without the docker container

Some Continuous Integration environments require access to non-default compilers and/or non-standard libraries. To do this properly, the docker container should not be used due to it's isolated file system. Instead, you should use this action's python source code as an installed python package (see below).

Using the python source code

This action was originally designed to only be used on a runner with the Ubuntu Operating System. However, this action's source code (essentially a python package) can be used on any runner using the Windows, Ubuntu, or possibly even MacOS (untested) virtual environments.

Note, some runners already ship with clang-format and/or clang-tidy. As of this writing, the following versions of clang-format and clang-tidy are already available:

This example makes use of another action (KyleMayes/install-llvm-action) to install a certain version of clang-tidy and clang-format.

on:
  pull_request:
    types: [opened, reopened]  # let PR-synchronize events be handled by push events
  push:

jobs:
  cpp-linter:
    runs-on: windows-latest

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4

      # this step can be skipped if the desired
      # version already comes with the runner's OS
      - name: Install clang-tools
        uses: KyleMayes/install-llvm-action@v1
        with:
          # v13 is the recommended minimum for the Visual Studio compiler (on Windows)
          version: 14
          # specifying an install path is required (on Windows) because installing
          # multiple versions on Windows runners needs non-default install paths.
          directory: ${{ runner.temp }}/llvm

      - name: Install linter python package
        run: python3 -m pip install cpp-linter

      - name: run linter as a python package
        id: linter
        # Pass the installed path to the '--version' argument.
        # Alternatively, pass the version number.
        #     Example. run: cpp-linter --version=14
        # Omit the version option if using the default version available in the OS.
        run: cpp-linter --version=${{ runner.temp }}/llvm

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

All input options listed above are specified by pre-pending a --. You can also install this repo locally and run cpp-linter -h for more detail. For example:

      - uses: cpp-linter/cpp-linter-action@v1
        with:
          style: file
          tidy-checks: '-*'
          files-changed-only: false
          ignore: 'dist/third-party-lib'

is equivalent to

      - name: Install linter python package
        run: python3 -m pip install cpp-linter

      - name: run linter as a python package
        run: |
          cpp-linter \
          --style=file \
          --tidy-checks='-*' \
          --files-changed-only=false \
          --ignore='dist/third-party-lib'

Example

Annotations

clang-format annotations

clang-tidy annotations

Thread Comment

sample comment

Add C/C++ Lint Action badge in README

You can show C/C++ Lint Action status with a badge in your repository README

Example

[![cpp-linter](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/cpp-linter.yml)

cpp-linter

Have question or feedback?

To provide feedback (requesting a feature or reporting a bug) please post to issues.

License

The scripts and documentation in this project are released under the MIT License

About

A Github Action for linting C/C++ code integrating clang-tidy and clang-format to collect feedback provided in the form of file-annotations, thread-comments, workflow step-summary, and Pull Request reviews.

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks