CLANG-TIDY(1)

✨ NAME ✨

clang-tidy — bestie, this is the manual page for clang-tidy 16 💖

---

🦋 DESCRIPTION 🦋

Okay so here's the whole vibe — how you actually run it:

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

And now, the OPTIONS, because that's the main character of this page 💅

🌸 Generic Options 🌸

• --help — shows you the available options (and if you're nosy, --help-hidden shows even more 👀)
• --help-list — prints out the list of available options (again, --help-list-hidden for the extra secret ones)
• --version — tells you what version of this program you've got, no cap

👑 clang-tidy options 👑

• --checks=<string> — a comma-separated list of globs, and any glob can have a - prefix. The globs get processed in the order they show up in the list. A glob with no - prefix adds checks whose names match it to the set; a glob with the - prefix removes matching checks from the set of enabled checks. Whatever you put here gets appended onto the value of the Checks option in the .clang-tidy file, if there is one.
• --config=<string> — specifies a config in YAML/JSON format, like:

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

And 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> — gives 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 --config after it reads the config file you specified. Pick either --config-file or --config, bestie, not both 🙅‍♀️
• --dump-config — dumps the configuration in YAML format to stdout. You can use this alongside a file name (and -- if the file lives outside a project that has a configured compilation database) and it'll print the config that was used for that file. Run it with -checks=* to also include the configuration of all the checks.
• --enable-check-profile — turns on per-check timing profiles and prints a report to stderr, so you can see where the time is going ⏱️
• --explain-config — for every enabled check, explains where it got enabled — in the clang-tidy binary, on the command line, or in a specific configuration file.
• --export-fixes=<filename> — a YAML file to store the suggested fixes in. You can then apply those stored fixes to the input source code with clang-apply-replacements.
• --extra-arg=<string> — an extra argument to append to the compiler command line
• --extra-arg-before=<string> — an extra argument to prepend to the compiler command line
• --fix — applies the suggested fixes. Heads up: without -fix-errors, clang-tidy will bail out if any compilation errors were found 🚨
• --fix-errors — applies suggested fixes even if compilation errors were found. And if the compiler errors have fix-its attached to them, clang-tidy applies 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. Fair warning: specifying this flag implicitly enables the --fix flag.
• --format-style=<string> — the style used for formatting code around applied fixes:
  • 'none' (that's the default) turns formatting off entirely
  • 'file' (literally the word file, it is 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' — the classic named styles. 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 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, periodt. Can be used together with -line-filter. 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, like:

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

• --list-checks — lists all the enabled checks and exits. Use it with -checks=* to list every check that's available.
• --load=<pluginfilename> — loads the plugin you point at
• -p <string> — build path
• --quiet — runs clang-tidy in quiet mode. This suppresses printing statistics about ignored warnings, and warnings that got treated as errors, if the respective options for those are specified 🤫
• --store-check-profile=<prefix> — by default the reports get printed in tabulated format to stderr. When you pass this option, those per-TU profiles are stored as JSON instead.
• --system-headers — displays the errors coming from system headers
• --use-color — uses colors in diagnostics. If it's not set, colors get used when the terminal connected to standard output supports colors. This option overrides the UseColor option in the .clang-tidy file, if there is one 🌈
• --verify-config — checks the config files to make sure every check and every option is actually recognized
• --vfsoverlay=<filename> — overlays the virtual filesystem described by that 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 onto the value of the WarningsAsErrors option in the .clang-tidy file, if there is one.

---

Okay so now the ✨important✨ stuff:

-p <build-path> is what you use 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 that output). When no build path is specified, clang-tidy will attempt a search for compile_commands.json through all the 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> ... is where you specify the paths of your source files. These paths get looked up in the compile command database. Here's the tea: if the path of a file is absolute, it needs to point into CMake's source tree. If the path is relative, then 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. Any "./" prefixes on relative files get automatically removed, but the rest of a relative path has to be a suffix of a path in the compile command database. Fr fr, that's the rule 🫶

🎀 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, then the configuration file in the parent directory (if one exists) gets taken, and the current config file is applied on top of the parent one. And if any configuration options have a corresponding command-line option, the command-line option takes precedence. You can inspect the effective configuration using -dump-config:

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

---

And that's the whole page, bestie!! 💜 This was clang-tidy 16, from October 2023 — slay, go forth and tidy your code, you've absolutely got this 👑✨