CLANG-TIDY(1)

🌸 NAME 🌸

clang-tidy — the manual page for clang-tidy 21. It lives in section 1 (User Commands), iykyk. 💅

---

💖 DESCRIPTION 💖

okay so bestie, here's literally how you run the thing:

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

and now the options, all of them, no skips, no cap 👑

---

⭐ OPTIONS ⭐

✨ Generic Options ✨

• --help — shows you every available option (--help-hidden gets you even more, if you're nosy 🫣)
• --help-list — prints the list of available options (--help-list-hidden for the extra secret ones)
• --version — tells you what version of this program you're on, iconic behavior

💅 clang-tidy options 💅

• --allow-no-checks — lets you have zero checks enabled and not get yelled at. It suppresses that "no checks enabled" error you'd otherwise get when you turn off every single check. living on the edge fr 💀
• --checks=<string> — a comma-separated list of globs, each optionally prefixed with -. The globs get processed in the order they appear in the list. Globs without the - prefix add checks with matching names to the set, and globs with the - prefix remove checks with matching names from the set of enabled checks. The value you pass here gets appended to the value of the 'Checks' option in the .clang-tidy file, if there is one. adding, not replacing, queen 🌈
• --config=<string> — specifies a configuration in YAML/JSON format, like this:

-config="{Checks: '*',
CheckOptions: {x: y}}"

When the value is empty, clang-tidy will go hunting for a file named .clang-tidy for each source file, checking its parent directories 🕵️

• --config-file=<string> — specify the path of a .clang-tidy or a custom config file, e.g. --config-file=/some/path/myTidyConfigFile. Internally this option works exactly the same way as the --config option, after reading the specified config file.

🚨 Use either --config-file or --config. Not both. pick a lane bestie 😭

• --dump-config — dumps the configuration in YAML format to stdout. You can use it together with a file name (and '--' if the file is outside of a project with a configured compilation database) and it'll print the configuration used for that file. Team it up with -checks=* to include the configuration of all checks. the full tea ☕
• --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 within modules. This feature may cause performance and parsing issues and is therefore considered experimental. proceed with caution, bestie 🧪
• --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 the .clang-tidy file, if any.
• --explain-config — for each enabled check it explains where it got enabled, i.e. in the clang-tidy binary, on the command line, or in a specific configuration file. the receipts 🧾
• --export-fixes=<filename> — the YAML file to store suggested fixes in. Those 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. no fixes for you 🚫
• --fix-errors — apply suggested fixes even if compilation errors were found. If the compiler errors have attached fix-its, clang-tidy will apply them as well. bold move 👑
• --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 will implicitly enable the '--fix' flag.
• --format-style=<string> — the style for formatting code around applied fixes, and here are your choices bestie:
  • 'none' (the default) turns off formatting
  • '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 information about formatting styles and options. This option overrides the 'FormatStyle\`` option in the .clang-tidy` file, if any.

• --header-filter=<string> — a regular expression matching the names of the headers to output diagnostics from. 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 the .clang-tidy file, if any.
• --line-filter=<string> — a list of files with line ranges to filter the warnings by. Can be used together with -header-filter. The format of the list is a JSON array of objects:

[ {"name":"file1.cpp","lines":[[1,3],[5,7]]},
{"name":"file2.h"} ]

• --list-checks — list all the enabled checks and exit. Use it with -checks=* to list all available checks. the whole roster 📋
• --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 warnings treated as errors, if the respective options were specified. shhh 🤫
• --store-check-profile=<prefix> — by default the reports are printed in tabulated format to stderr. When this option is passed, these per-TU profiles are instead stored as JSON. 💾✨
• --system-headers — display the errors from system headers. This option overrides the 'SystemHeaders' option in the .clang-tidy file, if any.
• --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 the .clang-tidy file, if any. 🌈🎨
• --verify-config — check the config files to make sure each check and option is recognized, without running any checks. a lil vibe check for your config 💅
• --vfsoverlay=<filename> — overlay the virtual filesystem described by file over the real file system.
• --warnings-as-errors=<string> — upgrades warnings to errors. Same format as '-checks'. This option's value is appended to the value of the 'WarningsAsErrors' option in the .clang-tidy file, if any. consequences 📈

---

-p <build-path> 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 (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> ... specify the paths of source files. These paths are 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 will be automatically removed, but the rest of a relative path must be a suffix of a path in the compile command database. pin down those paths bestie 📍

---

🎀 Parameters files 🎀

A large number of options or source files can be passed as parameter files by using '@parameter-file' on the command line. so efficient 💅

---

🦋 Configuration files 🦋

clang-tidy attempts 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. 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.
• 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 to determine if a given diagnostic is located in a header file.
• HeaderFilterRegex — same as '--header-filter'.
• ImplementationFileExtensions — file extensions to consider to determine 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 any exists) will be taken and the current config file will be applied on top of the parent one. ✨
• SystemHeaders — same as '--system-headers'.
• UseColor — same as '--use-color'.
• User — specifies the name or e-mail of the user running clang-tidy. This option is used, for example, to place the correct user name in TODO() comments in the relevant check.
• WarningsAsErrors — same as '--warnings-as-errors'.

The effective configuration can be inspected using --dump-config:

$ clang-tidy --dump-config

---
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'
...

---

and that's the whole page bestie, no notes 💖 that was clang-tidy 21, from way back in September 2026, delivering the lore straight from the manual's CLANG-TIDY(1) era. slay, go fix some code ✨🦋👑