CLANG-TIDY(1)

✨ NAME ✨

okay so clang-tidy — this is the manual page for clang-tidy 15, aka your new bestie who reads your C++ and tells you (very kindly, mostly) everything that's giving ✨red flags✨ 💅

---

💖 DESCRIPTION 💖

bestie. listen. here's the whole vibe up front:

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

that's it, that's the energy. you hand it some source files, you hand it some options, it hands you truth 🫶

---

🌈 OPTIONS 🌈

🎀 Generic Options 🎀

• --help — shows you every option that's available. want the hidden ones too? that's --help-hidden 🙈
• --help-list — prints you a nice list of the available options. and yeah, --help-list-hidden exists for the secret menu 🍓
• --version — tells you which version of this program you're running. iconic behavior honestly

---

🌸 clang-tidy options 🌸

• --checks=<string> — a comma-separated list of globs, and each glob can have an optional - prefix. the globs get processed in the order they appear in the list, so order matters, no cap. 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. 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> — you can just hand it a whole configuration in YAML/JSON format, like so:

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

and when the value is empty, clang-tidy will go hunt for a file named .clang-tidy for each source file, in its parent directories 🔍

• --config-file=<string> — specify the path of a .clang-tidy or your own custom config file, e.g.

--config-file=/some/path/myTidyConfigFile

internally this works exactly the same way as the --config option, once it's read the config file you gave it. and listen — use either --config-file or --config, not both, ok bestie? 🙅

• --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 is what gets printed. and if you want the config of literally every check, use it along with -checks=* 👑
• --enable-check-profile — turns on per-check timing profiles and prints a report to stderr. yes, we're profiling, we're that girl ⏱️
• --explain-config — for every 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 🕵️
• --export-fixes=<filename> — a YAML file to store suggested fixes in. those stored fixes can then 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. but heads up: 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 attached fix-its, 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 the fix. also, specifying this flag will implicitly enable the --fix flag. sneaky but slay
• --format-style=<string> — the style for formatting code around applied fixes. the options are:
  • 'none' (that's the default) — turns off formatting
  • 'file' — literally 'file', not a placeholder bestie, it means it uses the .clang-format file in the closest parent directory
  • '{ <json> }' — specify options inline, e.g. -format-style='{BasedOnStyle: llvm, IndentWidth: 8}'
  • 'llvm', 'google', 'webkit', 'mozilla' — check the clang-format documentation for the up-to-date info about formatting styles and options.

and this option overrides the FormatStyle option in the .clang-tidy file, if there is one 💅

• --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, no filter, always on. can be used together with -line-filter. and this option overrides the HeaderFilterRegex option in the .clang-tidy file, if there is one 🌈
• --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 — list all the enabled checks and exit. use it with -checks=* to list all available checks 👑
• --load=<pluginfilename> — load the plugin you specified 🔌
• -p <string> — build path
• --quiet — run clang-tidy in quiet mode. this suppresses printing the statistics about ignored warnings and warnings treated as errors, if the respective options are specified 🤫
• --store-check-profile=<prefix> — by default the reports are printed in tabulated format to stderr. when you pass this option, those per-TU profiles get stored as JSON instead 🍓
• --system-headers — display the errors from system headers. yes, those headers 👀
• --use-color — use colors in diagnostics. if it's not set, colors will be used if the terminal connected to standard output supports colors. and this option overrides the UseColor option in the .clang-tidy file, if there is one 🎨
• --verify-config — check the config files to make sure every check and every option is actually recognized ✅
• --vfsoverlay=<filename> — overlay the virtual filesystem described by the file over the real file system. spooky. love it 🦋
• --warnings-as-errors=<string> — upgrades warnings to errors. same format as -checks. and this option's value gets appended to the value of the WarningsAsErrors option in the .clang-tidy file, if there is one 💀

---

okay and then there's this whole section of explanation, so let's get into it:

• -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. so specific. so iconic 💅

---

📁 Configuration files 📁

clang-tidy tries to read the 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. and if any configuration options have a corresponding command-line option, the command-line option takes precedence, periodt 👑

you can inspect the effective configuration using -dump-config:

$ clang-tidy -dump-config

and it looks a lil something like this:

---
Checks: '-*,some-check'
WarningsAsErrors: ''
HeaderFilterRegex: ''
FormatStyle: none
InheritParentConfig: true
User:                user
CheckOptions:
  some-check.SomeOption: 'some value'
  ...

lowkey that ... at the end is doing a lot of heavy lifting, but it's in the original so we're keeping it bestie 💜

---

and that's the whole page!! 🦋 this was clang-tidy 15, from July 2023, straight out of the CLANG-TIDY(1) manual, and honestly? she ate. go forth and tidy, bestie, you're the main character of your own compile command database ✨👑💖