clang-tidy

Run default checks on a source file

$ clang-tidy [path/to/file.cpp]

$ clang-tidy [path/to/file.cpp] -checks=[-*,cppcoreguidelines-*]

$ clang-tidy -checks=[*] -list-checks

$ clang-tidy [path/to/file.cpp] -- -I[my_project/include] -D[definitions]

clang-tidy [options] -- [compiler options]

Example: clang-tidy -checks='clang-diagnostic-*' -p build/ src/main.cpp -- -std=c++17

-checks=
    Specifies a comma-separated list of checks to enable or disable. Wildcards (*) are supported. For example, -checks='clang-diagnostic-*,modernize-*'.

-config=
    Specifies configuration in YAML format directly or a path to a .clang-tidy config file. This allows global or per-directory configuration of checks and options.

-header-filter=
    Regular expression to match header files that should be analyzed. Useful for limiting analysis to project-specific headers, preventing analysis of system headers.

-fix
    Applies suggested fixes for detected issues automatically. Use with caution, as it modifies source files. Consider using -fix-errors for only error-level fixes.

-p
    Specifies the path to the build directory containing the compile_commands.json file. This file is crucial for clang-tidy to accurately understand compilation flags for each source file.

-extra-arg=
-extra-arg-before=
    Passes additional arguments directly to the Clang compiler invocation for each analyzed file. Useful for adding include paths, preprocessor definitions, or other compiler-specific flags.

--
    A separator indicating that all subsequent arguments are compiler options and should be passed directly to the underlying Clang compiler. Essential when compile_commands.json is not used or needs augmentation.

clang-tidy is a powerful, extensible static analysis and linter tool for C, C++, and Objective-C code. Built on the Clang compiler frontend, it identifies various programming errors, style violations, and potential bugs. It provides an extensible framework for diagnosing and fixing typical programming errors, style violations, and API misuses. clang-tidy integrates seamlessly with modern build systems (like CMake) by leveraging the compile_commands.json file, which provides compilation flags for each source file. It helps enforce coding standards, improve code quality, and detect issues early in the development cycle, making codebases more maintainable and robust. Many checks are available out-of-the-box, covering areas from performance to security, and custom checks can be easily implemented.
It also supports automatic application of suggested fixes.

Requires a compile_commands.json file for accurate analysis in most complex projects, which can be generated by build systems like CMake.
Can be computationally intensive and slow on large codebases, requiring careful configuration and selective check enabling.
Some checks might produce false positives, requiring manual review, careful configuration, or suppression directives in code.
Automatic fixes (with -fix) should always be reviewed and version-controlled before committing changes, as they might not always align perfectly with developer intent.

clang-tidy can be configured using .clang-tidy files placed in the project directory hierarchy. These YAML-formatted files allow fine-grained control over which checks are enabled/disabled, their options, and how they behave. Configuration can be global (e.g., in your home directory) or specific to subdirectories, with configuration files closer to the source file overriding more distant ones.

For effective use, clang-tidy relies on accurate compiler flags for correct parsing and semantic analysis. This is best achieved by generating a compile_commands.json file from your build system (e.g., using CMake with -DCMAKE_EXPORT_COMPILE_COMMANDS=ON). Tools like run-clang-tidy.py (often provided with Clang distributions) simplify running clang-tidy across an entire project based on this file, processing all relevant source files defined within it.

clang-tidy originated as part of the LLVM project, leveraging the Clang compiler's robust parsing and semantic analysis capabilities. It was developed to provide a powerful, open-source alternative to commercial static analysis tools for C, C++, and Objective-C, enabling deeper code insights and seamless integration into CI/CD pipelines. Its development is ongoing, with new checks and features continually added by the community.

clang-format(1), scan-build(1), cppcheck(1), gcc(1), clang(1), cmake(1)