Command Line Interface Options

Note

These options have a direct relationship with the cpp-linter-action user inputs. Although, some default values may differ.

Usage
cpp-linter [-h] [-v VERBOSITY] [-p DATABASE] [-s STYLE]
           [-c TIDY_CHECKS] [-V VERSION] [-e EXTENSIONS] [-r REPO_ROOT]
           [-i IGNORE] [-M IGNORE_FORMAT] [-D IGNORE_TIDY]
           [-l LINES_CHANGED_ONLY] [-f FILES_CHANGED_ONLY] [-g NO_LGTM]
           [-t {true,false,update}] [-w STEP_SUMMARY]
           [-a FILE_ANNOTATIONS] [-x EXTRA_ARG] [-d TIDY_REVIEW]
           [-m FORMAT_REVIEW] [-R PASSIVE_REVIEWS] [-j JOBS]
           [files ...]

Positional Arguments

files

A space separated list of files to focus on. These files will automatically be added to the list of explicitly not-ignored files. While other filtering is done with --extensions, the files specified as positional arguments will be exempt from explicitly ignored domains (see --ignore).

Optional Arguments

-v, --verbosity

1.4.6 Default'info'

This controls the action’s verbosity in the workflow’s logs. Supported options are debug and info. The numerical representations of these log levels defined by the logging library (10 for debug, and 20 for info) are also supported.

This option does not affect the verbosity of resulting thread comments, file annotations, nor log grouping markers.

-p, --database

1.4.6 Default''

The path that is used to read a compile command database. For example, it can be a CMake build directory in which a file named compile_commands.json exists (set CMAKE_EXPORT_COMPILE_COMMANDS to ON). When no build path is specified, a search for compile_commands.json will be attempted through all parent paths of the first input file. See https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an example of setting up Clang Tooling on a source tree.

Important

Builds using ninja should explicitly specify this path. Otherwise, cpp-linter will have difficulty parsing clang-tidy output

-s, --style

1.4.6 Default'llvm'

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 using clang-format entirely.

See clang-format docs for more info.

Note

If this is not a blank string, then it is also passed to clang-tidy (if --tidy-checks is not -*). This is done ensure a more consistent output about suggested fixes between clang-tidy and clang-format.

-c, --tidy-checks

1.4.6 Default'boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*'

A 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 ('').

See also clang-tidy docs for more info.

-V, --version

1.4.6 Default''

The desired version of the clang tools to use.

  • 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). All paths specified here are converted to absolute.

-e, --extensions

1.4.6 Default'c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx'

The file extensions to analyze. This is a comma-separated string of extensions.

-r, --repo-root

1.4.6 Default'.'

The relative path to the repository root directory. This path is relative to the working directory from which cpp-linter was executed.

-i, --ignore

1.4.6 Default'.github'

Set this option with path(s) to ignore (or not ignore).

  • In the case of multiple paths, you can use | to separate each path.

  • There is no need to use ./ for each entry; a blank string ('') represents the --repo-root path.

  • This can also have files, but the file’s path (relative to the --repo-root) has to be specified with the filename.

  • Submodules are automatically ignored. Hidden directories (beginning with a .) are also ignored automatically.

  • Prefix a path with ! to explicitly not ignore it. This can be applied to a submodule’s path (if desired) but not hidden directories.

  • Added in version 1.9: Glob patterns are supported here.

    All asterisk characters (*) are not literal as they were before. See glob() for more details about Unix style glob patterns.

-M, --ignore-format

1.9.0 Default''

Set this option with path(s) to ignore (or not ignore) when using clang-format. See --ignore for more detail

-D, --ignore-tidy

1.9.0 Default''

Set this option with path(s) to ignore (or not ignore) when using clang-tidy. See --ignore for more detail

-l, --lines-changed-only

1.4.6 Default'false' contents: read

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.

-f, --files-changed-only

1.4.6 Default'false' contents: read

Set this option to false to analyze any source files in the repo. This is automatically enabled if --lines-changed-only is enabled.

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 the changed files for an event.

See Authenticating with the GITHUB_TOKEN

-g, --no-lgtm

1.6.1 Default'true'

Set this option to true or false to enable or disable the use of a thread comment or PR review that basically says ‘Looks Good To Me’ (when all checks pass).

Seealso

The --thread-comments option also notes further implications.

-t, --thread-comments

1.6.1 Default'false' contents: write

This controls the behavior of posted thread comments as feedback. The following options are supported:

  • true: enable the use of thread comments. This will always delete an outdated thread comment and post a new comment (triggering a notification for every comment).

  • update: update an existing thread comment if one already exists. This option does not trigger a new notification for every thread comment update.

  • false: disable the use of thread comments.

Note

To use thread comments, the GITHUB_TOKEN (provided by Github to each repository) must be declared as an environment variable.

See Authenticating with the GITHUB_TOKEN

-w, --step-summary

1.6.0 Default'false'

Set this option to true or false to enable or disable the use of a workflow step summary when the run has concluded.

-a, --file-annotations

1.4.6 Default'true'

Set this option to false to disable the use of file annotations as feedback.

-x, --extra-arg

1.4.7 Default''

A string of extra arguments passed to clang-tidy for use as compiler arguments. This can be specified more than once for each additional argument. Recommend using quotes around the value and avoid using spaces between name and value (use = instead):

cpp-linter --extra-arg="-std=c++17" --extra-arg="-Wall"
-d, --tidy-review

1.7.0 Default'false' experimental pull-requests: write

Set to true to enable Pull Request reviews from clang-tidy.

-m, --format-review

1.7.0 Default'false' pull-requests: write

Set to true to enable Pull Request reviews from clang-format.

-R, --passive-reviews

1.10.0 Default'false' pull-requests: write

Set to true to prevent Pull Request reviews from requesting or approving changes

-j, --jobs

1.8.1 Default'1'

Set the number of jobs to run simultaneously. If set less than or equal to 0, the number of jobs will be set to the number of all available CPU cores.