CLANG-TIDY(1)

📦
version 22.1.8 · 3 versions
, in ubuntu stonking

🦋 CLANG-TIDY 🦋

okay bestie, welcome to the manual page for clang-tidy 22 — she's the linter/static-analyzer bestie of the LLVM world and she is so iconic. let's get into it 💅

✨ NAME ✨

clang-tidy — manual page for clang-tidy 22

🌸 DESCRIPTION 🌸

here's the vibe, the whole ~usage~ moment:

USAGE: clang-tidy [options] <source0> [... <sourceN>]

and then... the options 😭 so many options. but we're gonna get through them together, no cap.

💖 Generic Options 💖

the basic-girl options. everyone needs them.

  • --help — shows you all the available options (--help-hidden gets you even more 👀)
  • --help-list — shows you the list of available options (--help-list-hidden for even more than that)
  • --version — tells you which version of this program you're running

🎀 clang-tidy options 🎀

this is the main character section, fr fr.

  • --allow-no-checks — lets you have an empty set of enabled checks. this suppresses the whole "no checks enabled" error that would otherwise pop off when you disable literally all of them.
  • --checks=<string> — a comma-separated list of globs, each one optionally prefixed with -. globs get processed in the order they show up in the list. globs without the - prefix add checks with matching names into the set; globs with the - prefix remove checks with matching names from the set of enabled checks. and this option's value gets appended to whatever the Checks option in your .clang-tidy file says, if there is one.
  • --config=<string> — specify a config in YAML/JSON format, like:
-config="{Checks: '*',
CheckOptions: {x: y}}"

when the value is empty, clang-tidy will try to find a file named .clang-tidy for each source file in its parent directories.

  • --config-file=<string> — point at the path of your .clang-tidy or custom config file, e.g. --config-file=/some/path/myTidyConfigFile. inside, this option works exactly the same way as the --config option does, just after it reads the specified config file. and bestie — use either --config-file or --config, never both 🙅
  • --dump-config — dumps the configuration to stdout in YAML format. you can use this along with a file name (and -- if the file lives outside of a project with a configured compilation database). the configuration used for that file will be what gets printed. use it along with -checks=* to include the configuration of all the checks.
  • --enable-check-profile — turns on per-check timing profiles and prints a report to stderr.
  • --enable-module-headers-parsing — enables preprocessor-level module header parsing for C++20 and above, which empowers specific checks to detect macro definitions inside modules. heads up though: this feature may cause performance and parsing issues, so it's considered experimental 🔬
  • --exclude-header-filter=<string> — a regular expression matching the names of the headers to exclude diagnostics from. diagnostics from the main file of each translation unit are always displayed no matter what. must be used together with --header-filter. can be used together with -line-filter. this option overrides the ExcludeHeaderFilterRegex option in .clang-tidy, if there is one.
  • --experimental-custom-checks — enables experimental clang-query based custom checks. see https://clang.llvm.org/extra/clang-tidy/QueryBasedCustomChecks.html.
  • --explain-config — for each enabled check, explains where it's enabled — like in the clang-tidy binary, on the command line, or in a specific configuration file. she's giving receipts 💅
  • --export-fixes=<filename> — a YAML file to store suggested fixes in. the stored fixes can be applied to the input source code with clang-apply-replacements.
  • --extra-arg=<string> — an additional argument to append to the compiler command line
  • --extra-arg-before=<string> — an additional argument to prepend to the compiler command line
  • --fix — apply the suggested fixes. without -fix-errors, clang-tidy will bail out if any compilation errors were found.
  • --fix-errors — apply suggested fixes even if compilation errors were found. and if compiler errors have fix-its attached, clang-tidy will apply those too.
  • --fix-notes — if a warning has no fix, but a single fix can be found through an associated diagnostic note, apply that fix. specifying this flag implicitly enables the --fix flag.
  • --format-style=<string> — the style used for formatting code around applied fixes:
    • 'none' (this is the default) turns formatting off
    • 'file' (literally the word file, not a placeholder) uses the .clang-format file in the closest parent directory
    • '{ <json> }' specifies options inline, e.g. -format-style='{BasedOnStyle: llvm, IndentWidth: 8}'
    • 'llvm', 'google', 'webkit', 'mozilla' — see the clang-format documentation for the up-to-date info about formatting styles and options. this option overrides the FormatStyle option in .clang-tidy, if there is one.
  • --header-filter=<string> — a regular expression matching the names of the headers to output diagnostics from. the default value is '.*', meaning diagnostics from all non-system headers are displayed by default. diagnostics from the main file of each translation unit are always displayed. can be used together with -line-filter. this option overrides the HeaderFilterRegex option in .clang-tidy, if there is one.
  • --line-filter=<string> — a list of files and line ranges to output diagnostics from. the range is inclusive on both ends. can be used together with -header-filter. the format of the list is a JSON array of objects, like:
[      {"name":"file1.cpp","lines":[[1,3],[5,7]]}, {"name":"file2.h"}
]

this will output diagnostics from 'file1.cpp' only for the line ranges [1,3] and [5,7], plus everything from all of 'file2.h'.

  • --list-checks — list all enabled checks and exit. use it with -checks=* to list all available checks.
  • --load=<pluginfilename> — load the specified plugin 🔌
  • -p <string> — build path
  • --quiet — run clang-tidy in quiet mode. this suppresses printing statistics about ignored warnings and about warnings treated as errors, if those respective options were specified.
  • --removed-arg=<string> — a list of arguments to remove from the command line sent to the compiler. ⚠️ please note: removing arguments might change the semantics of the analyzed code, possibly leading to compiler errors, false positives or false negatives. this option is applied before --extra-arg and --extra-arg-before.
  • --store-check-profile=<prefix> — by default reports are printed in tabulated format to stderr. when this option is passed, those per-TU profiles get stored as JSON instead.
  • --system-headers — display the errors from system headers. this option overrides the SystemHeaders option in .clang-tidy, if there is one.
  • --use-color — use colors in diagnostics. if it's not set, colors will be used if the terminal connected to standard output supports colors. this option overrides the UseColor option in .clang-tidy, if there is one. 🌈
  • --verify-config — check the config files to make sure each check and option is recognized, without running any checks at all.
  • --vfsoverlay=<filename> — overlay the virtual filesystem described by file on top of the real file system.
  • --warnings-as-errors=<string> — upgrades warnings to errors. same format as '-checks'. this option's value gets appended to the value of the WarningsAsErrors option in .clang-tidy, if there is one.

-p <build-path> is used to read a compile command database.

for example, it can be a CMake build directory that has a file named compile_commands.json in it (use the -DCMAKE_EXPORT_COMPILE_COMMANDS=ON CMake option to get this output). 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.

<source0> ... specifies the paths of source files. these paths get looked up in the compile command database. if the path of a file is absolute, it needs to point into CMake's source tree. if the path is relative, the current working directory needs to be in the CMake source tree and the file must be in a subdirectory of the current working directory. "./" prefixes in the relative files get removed automatically, but the rest of a relative path must be a suffix of a path in the compile command database.

🧚 Parameters files 🧚

a large number of options or source files can be passed as parameter files by using '@parameter-file' in the command line. slay, batch it up.

🍓 Configuration files 🍓

clang-tidy tries to read configuration for each source file from a .clang-tidy file located in the closest parent directory of the source file. the .clang-tidy file is specified in YAML format. and important: if any configuration options have a corresponding command-line option, the command-line option takes precedence 👑

the following configuration options may be used in a .clang-tidy file:

  • CheckOptions — list of key-value pairs defining check-specific options. example:
CheckOptions:
some-check.SomeOption: 'some value'
  • Checks — same as '--checks'. additionally, the list of globs can be specified as a list instead of a string.
  • CustomChecks — array of user defined checks based on Clang-Query syntax.
  • ExcludeHeaderFilterRegex — same as '--exclude-header-filter'.
  • ExtraArgs — same as '--extra-arg'.
  • ExtraArgsBefore — same as '--extra-arg-before'.
  • FormatStyle — same as '--format-style'.
  • HeaderFileExtensions — file extensions to consider when determining if a given diagnostic is located in a header file.
  • HeaderFilterRegex — same as '--header-filter'.
  • ImplementationFileExtensions — file extensions to consider when determining if a given diagnostic is located in an implementation file.
  • InheritParentConfig — if this option is true in a config file, the configuration file in the parent directory (if one exists) will be taken, and the current config file will be applied on top of the parent one. iconic inheritance moment 💅
  • RemovedArgs — same as '--removed-arg'.
  • SystemHeaders — literally the same thing as --system-headers. Same energy, different outfit. ✨
  • UseColor — same as --use-color. Yeah bestie, it's a vibe match. 🌈
  • User — here you put the name or the e-mail of the user running clang-tidy. What's it for, you ask? It's used, for example, to drop the correct user name into TODO() comments in the relevant check. So the checks can leave little notes addressed to you. Cute, honestly. 💌
  • WarningsAsErrors — same as --warnings-as-errors. No cap. 🔥

And if you wanna see what your config actually ended up being (because vibes can deceive), the effective configuration can be inspected using --dump-config:

$ clang-tidy --dump-config

which gives you something like:

Checks:
  '-*,some-check'

WarningsAsErrors:
  ''

HeaderFileExtensions:
  ['', 'h','hh','hpp','hxx']

ImplementationFileExtensions: ['c','cc','cpp','cxx']
HeaderFilterRegex:            '.*'
FormatStyle:                  none
InheritParentConfig:          true
User:                         user
CheckOptions:
  some-check.SomeOption: 'some value'
  ...
Look at her. All your settings, laid bare, alphabetically-ish, no secrets between you two. 🫶

And that's the whole page, bestie!! 💅 This lil' masterpiece is from clang-tidy 22, dated September 2026, and it's filed under CLANG-TIDY(1) in the man pages, exactly where it belongs. Go forth and tidy your C++ — not me being the most organized girl in the terminal fr fr. ✨🎀🦋💖

📦 where this page comes from