CLANG-TIDY(1)

💖 NAME 💖

clang-tidy — bestie's fave little linting icon, manual page for clang-tidy 14 ✨

---

✨ DESCRIPTION ✨

okay so here's the whole vibe, the usage is literally this:

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

and then, the OPTIONS. buckle up 🎀

🌸 OPTIONS 🌸

💅 Generic Options

• --help — shows you all the available options (--help-hidden if you want the extra secret ones too 👀)
• --help-list — prints out the list of available options (--help-list-hidden for the hidden version, iykyk)
• --version — tells you what version of this program you're running, slay

🦋 clang-tidy options

• --checks=<string> — a comma-separated list of globs, each one optionally prefixed with -. The globs get processed in order of appearance in the list, fr fr. Globs with no - prefix add checks with matching names to the set; globs with a - prefix remove checks with matching names from the set of enabled checks. And btw, this option's value gets appended to the value of the Checks option in the .clang-tidy file, if there is one.
• --config=<string> — lets you specify a configuration in YAML/JSON format, like this:

-config="{Checks: '*',
          CheckOptions: [{key: x,

value: y}]}"

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

• --config-file=<string> — specify the path of a .clang-tidy file or a custom config file, e.g. --config-file=/some/path/myTidyConfigFile. Internally this works exactly the same way as the --config option, but after reading the specified config file. Use either --config-file or --config, not both. not both!! 😤
• --dump-config — dumps the configuration in YAML format to stdout. You can use this along with a file name (and -- if the file is outside of a project with a configured compilation database). The configuration used for that file will be printed. Use it along with -checks=* to include the configuration of all checks.
• --enable-check-profile — turns on per-check timing profiles and prints a report to stderr. performance girlies rise 🫶
• --explain-config — for each enabled check, it explains where it's enabled, i.e. in the clang-tidy binary, on the command line, or in a specific configuration file. receipts, basically 💅
• --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 — applies suggested fixes. Without -fix-errors, clang-tidy will bail out if any compilation errors were found. (so if things are broken, it's out ✌️)
• --fix-errors — applies suggested fixes even if compilation errors were found. If compiler errors have attached fix-its, clang-tidy will apply those too. brave. iconic.
• --fix-notes — if a warning has no fix, but a single fix can be found through an associated diagnostic note, apply the fix. Specifying this flag will implicitly enable the --fix flag. sneaky but helpful.
• --format-style=<string> — the style for formatting code around applied fixes:
  • 'none' (default) turns off formatting
  • 'file' (literally '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 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. 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 — lists all enabled checks and exits. Use it with -checks=* to list all available checks. the full menu, no cap 📋
• --load=<pluginfilename> — loads the specified plugin.
• -p=<string> — build path.
• --quiet — runs clang-tidy in quiet mode. This suppresses printing statistics about ignored warnings and warnings treated as errors, if the respective options are specified. shhh 🤫
• --store-check-profile=<prefix> — by default reports are printed in tabulated format to stderr. When this option is passed, those per-TU profiles are instead stored as JSON.
• --system-headers — displays the errors from system headers. yes, even those headers.
• --use-color — uses colors in diagnostics. If 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. pretty output supremacy 🌈
• --vfsoverlay=<filename> — overlays the virtual filesystem described by the 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. no more letting things slide 💀

---

okay and now the important lore:

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

🎀 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. If InheritParentConfig 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. If any configuration options have a corresponding command-line option, the command-line option takes precedence. The effective configuration can be inspected using -dump-config:

$ clang-tidy -dump-config

---

Checks:
       '-*,some-check'

WarningsAsErrors:
       ''

HeaderFilterRegex:
       ''

FormatStyle:
       none

       InheritParentConfig: true User:                user CheckOptions:

- key: some-check.SomeOption

value: 'some value'

       ...

---

heads up bestie: config options get overridden by their command-line twins, and --config-file and --config are strictly an either/or situation. choose wisely 💖

---

and that's the whole thing! this was clang-tidy 14, dated May 2025 — go forth and lint, you absolute main character 👑💜