[clang-tidy] Introduce HeaderFileExtensions and ImplementationFileExtensions options

[carlosgalvezp]

Summary

We have a number of checks designed to analyze problems
in header files only, for example:

bugprone-suspicious-include
google-build-namespaces
llvm-header-guard
misc-definitions-in-header
...

All these checks duplicate the same logic and options
to determine whether a location is placed in the main
source file or in the header. More checks are coming
up with similar requirements.

Thus, to remove duplication, let's move this option
to the top-level configuration of clang-tidy (since
it's something all checks should share).

Since the checks fetch the option via getLocalOrGlobal,
the behavior is unchanged.

Add a deprecation notice for all checks that use the
local option, prompting to update to the global option.

The functionality for parsing the option will need to
remain in the checks during the transition period.
Once the local options are fully removed, the goal
is to store the parsed options in the ClangTidyContext,
that checks can easily have access to.

[Eugene.Zelenko]

Looks OK for me, but probably will be good idea to remove check-specific options in same commit.

[carlosgalvezp]

In D141000#4026600, @Eugene.Zelenko wrote:

Looks OK for me, but probably will be good idea to remove check-specific options in same commit.

Thanks for the review! Sure, I can do that, I just thought we should try to keep commits as minimal as possible. I also wonder if we need to follow a formal deprecation process or we can just remove the option from existing checks directly?

@njames93 , as Code Owner, could you give your view on the general direction of the patch before I move forward? Thanks!

[njames93]

Can you explain the reasoning of why this approach is better than current approach where checks can use global options(Options.getLocalOrGlobal("HeaderFileExtensions", utils::defaultHeaderFileExtensions())) to access the same information?

Some checks also have the global option ImplementationFileExtensions, what's the proposal with that. Should checks that use this functionality carry on like that, use a negative match of this proposed option or should we also add that option to the ClangTidyOptions.

What is the migration plan for code-bases that currently use the old check-based option? We can't break their existing configs, likewise we have to be careful of projects with checked-in .clang-tidy files that make use of this new option when maintainers may still have an older version of clang-tidy.

Finally, Why would you make the option a semicolon delimited string. The only reason that's used for the current CheckOptions is there isn't currently a better alternative, For ClangTidyOptions we could set the type to be an Optional<std::vector<std::string>>. This would be more natural when writing the yaml file.

HeaderFileExtensions: [ h, hh, hxx, hpp, "" ]
# Or
HeaderFileExtensions:
  - h
  - hh
  - hxx
  - hpp
  - ""

[carlosgalvezp]

Thanks for the feedback!

Can you explain the reasoning of why this approach is better than current approach where checks can use global options(Options.getLocalOrGlobal("HeaderFileExtensions", utils::defaultHeaderFileExtensions())) to access the same information?

Nice, I wasn't aware of the getLocalOrGlobal function. It's unclear to me why some arguments are available via both command line and config, and others only via config. If there is no use case for CLI I agree the config-only option is sufficient, but I would like to properly document it. There's for example the option User: user that is undocumented. Perhaps I can restructure a bit the section Configuration files?

Some checks also have the global option ImplementationFileExtensions, what's the proposal with that. Should checks that use this functionality carry on like that, use a negative match of this proposed option or should we also add that option to the ClangTidyOptions.

For consistency I believe it makes sense to add it as well as a global option.

What is the migration plan for code-bases that currently use the old check-based option? We can't break their existing configs, likewise we have to be careful of projects with checked-in .clang-tidy files that make use of this new option when maintainers may still have an older version of clang-tidy.

We would follow a deprecation strategy. For example, we document in every check that the current options are deprecated, and users should instead use the global config. The local config can be removed after 2 clang releases (that would mean clang 18 here). Using getLocalOrGlobal should simplify the logic of supporting the transition I believe.

Finally, Why would you make the option a semicolon delimited string. The only reason that's used for the current CheckOptions is there isn't currently a better alternative, For ClangTidyOptions we could set the type to be an Optional<std::vector<std::string>>. This would be more natural when writing the yaml file.

Absolutely! The current format is very strange to me, but I kept it to keep the patch as minimal as possible. A vector of strings looks great.

[carlosgalvezp]

On a second thought, using getLocalOrGlobal would still require all checks to have 2 private member variables (the raw string option and the parsed header option), together with the logic in the constructor to get the option an parse that, as well as functions to storeOptions.

That's a lot of duplication that I would like to get rid of. Keeping those private variables to get a global option is also a bit inconsistent with the rest of checks and might cause confusion. What do you think?

[carlosgalvezp]

I found now what this global User option is about:

/// 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.
std::optional<std::string> User;

So it seems to me it's an option used only in one check, and yet it's a global option. Based on that I think it's reasonable to have HeaderFileExtensions and ImplementationFileExtensions (which are shared among multiple checks) as global as well. It doesn't need to be a CLI option, config-only is fine.

[njames93]

You do raise a good point about duplication, Therefore does it make sense to also do the same with the IncludeStyle as lots of checks add new includes.
Though there is a precedent to do away with LLVM/Google style, as clang-format should be responsible for reordering inserted includes.

In D141000#4030877, @carlosgalvezp wrote:

I found now what this global User option is about:

/// 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.
std::optional<std::string> User;

So it seems to me it's an option used only in one check, and yet it's a global option. Based on that I think it's reasonable to have HeaderFileExtensions and ImplementationFileExtensions (which are shared among multiple checks) as global as well. It doesn't need to be a CLI option, config-only is fine.

Yeah, I think there is definitely precedent to move that field out of the Options. IMO the google-readability-todo check should instead read that field from the Check GlobalOptions, and its default value should be set in the GoogleModule::getModuleOptions virtual function.

[carlosgalvezp]

Therefore does it make sense to also do the same with the IncludeStyle as lots of checks add new includes.

Sure, that could also be done, though I think it'd be preferable to do it in a separate patch. Personally I'm a bit reluctant to having formatting options in clang-tidy at all, since that is responsibility of clang-format - then a project has duplicated settings in both tools, and it gets tricky when they get in conflict. If a project cares about formatting they would most likely have clang-format as a pre-commit check anyway to take care of formatting after clang-tidy has fixed the rest. But if people want to keep the option I won't oppose :)

[carlosgalvezp]

• Add also ImplementationFileExtensions.
• Add deprecation notice to affected checks.

[carlosgalvezp]

Update commit message

[Eugene.Zelenko]

It'll be good idea to check that HeaderFileExtensions and ImplementationFileExtensions do not overlap.

[carlosgalvezp]

This comment was removed by carlosgalvezp.

[carlosgalvezp]

Since we are at it - are we happy with the name "ImplementationFileExtensions"? I think "SourceFileExtensions" is more common in the literature, and it would look more visually pleasing in the config file since it has the same length as "HeaderFileExtensions".

HeaderFileExtensions: ["h", "hh"]
ImplementationFileExtensions: ["c", "cc"]

vs

HeaderFileExtensions: ["h", "hh"]
SourceFileExtensions: ["c", "cc"]

[carlosgalvezp]

Add check to ensure HeaderFileExtensions and ImplementationFileExtensions
do not overlap.

[carlosgalvezp]

In D141000#4034305, @Eugene.Zelenko wrote:

It'll be good idea to check that HeaderFileExtensions and ImplementationFileExtensions do not overlap.

Good idea, done!

[carlosgalvezp]

In D141000#4034307, @carlosgalvezp wrote:

Since we are at it - are we happy with the name "ImplementationFileExtensions"? I think "SourceFileExtensions" is more common in the literature, and it would look more visually pleasing in the config file since it has the same length as "HeaderFileExtensions".

HeaderFileExtensions: ["h", "hh"]
ImplementationFileExtensions: ["c", "cc"]

vs

HeaderFileExtensions: ["h", "hh"]
SourceFileExtensions: ["c", "cc"]

Yes, there's a clear preference in the repo:

$ git grep -E [sS]ource.?[fF]ile | wc -l
5932
$ git grep -E [iI]mplementation.?[fF]ile | wc -l
104

Will change accordingly.

[carlosgalvezp]

On the other hand, the LLVM coding standards talk about "implementation file". Ok, will leave as is. Then I'd say it's ready for review! :)

[carlosgalvezp]

Rebase and fix formatting of "clang-tidy" in the docs.

[carlosgalvezp]

@Eugene.Zelenko @njames93 I believe I have addressed all the outstanding comments, is there anything else you think needs fix? Otherwise I would like to land the patch before January 24th when they will start a new release.

[Eugene.Zelenko]

Looks OK for me, but please improve Release Notes. Will be good idea to wait for developers approval.

clang-tools-extra/docs/ReleaseNotes.rst

109

Will be good idea to combine two sentences into one because options are closely related.

[carlosgalvezp]

Merge release notes into one line

[njames93]

On the topic of Objective-C, they use .m and .M extensions, it may be worth pointing out that this list is case sensitive (I'm assuming that's going to be the case.)

clang-tools-extra/clang-tidy/ClangTidyOptions.cpp

151–152

clang-tidy also works on ObjectiveC, ObjectiveC++ and cuda source files, We shouldn't be ignoring those in the defaults here.
Also some libraries(including the standard library) make use of extension-less header files, maybe its worth adding an empty entry in the header file extensions.

[carlosgalvezp]

clang-tools-extra/clang-tidy/ClangTidyOptions.cpp

151–152

Fully agree, but I'd like to keep the scope of this patch focused only on moving the options from local to global options - it should be a NFC. I took the defaults that we have today in all checks, which also happen to be the hardcoded defaults in FileExtensionUtils.h:

inline StringRef defaultHeaderFileExtensions() { return ";h;hh;hpp;hxx"; }

Adding more extensions requires changes to those source files as well, increase sizes of SmallVectors therein, etc, so I think it'd fit better as a separate patch. Would you agree?

By the way, does the initial semicolon above mean that we consider extension-less headers? I can fix that in this patch.

[carlosgalvezp]

Add missing empty header extension to the default list.

[carlosgalvezp]

Remove buggy empty extension for ImplementationFilesExtension

[carlosgalvezp]

@njames93 Let me know if you are happy with the patch, I'd like to land before 24th of January :)

[Eugene.Zelenko]

D142123 also cries for it :-) Somehow I was not able to make comments there :-(

[carlosgalvezp]

In D141000#4071793, @Eugene.Zelenko wrote:

D142123 also cries for it :-) Somehow I was not able to make comments there :-(

Yep, one more reason to get this in asap :)

clang-tools-extra/clang-tidy/ClangTidyOptions.h

[[nodiscard]] ClangTidyOptions merge(const ClangTidyOptions &Other,
                                        unsigned Order) const;
 
   /// Checks filter.
   std::optional<std::string> Checks;
 
   /// WarningsAsErrors filter.
   std::optional<std::string> WarningsAsErrors;
 
+  /// File extensions to consider to determine if a given diagnostic is located
+  /// in a header file.
+  std::optional<std::vector<std::string>> HeaderFileExtensions;
+
+  /// File extensions to consider to determine if a given diagnostic is located
+  /// is located in an implementation file.
+  std::optional<std::vector<std::string>> ImplementationFileExtensions;
+
   /// Output warnings from headers matching this filter. Warnings from
   /// main files will always be displayed.
   std::optional<std::string> HeaderFilterRegex;
 
   /// Output warnings from system headers matching \c HeaderFilterRegex.
   std::optional<bool> SystemHeaders;
 
   /// Format code around applied fixes with clang-format using this

clang-tools-extra/clang-tidy/ClangTidyOptions.cpp

void yamlize(IO &IO, ClangTidyOptions::OptionMap &Options, bool,
   }
 }
 
 template <> struct MappingTraits<ClangTidyOptions> {
   static void mapping(IO &IO, ClangTidyOptions &Options) {
     bool Ignored = false;
     IO.mapOptional("Checks", Options.Checks);
     IO.mapOptional("WarningsAsErrors", Options.WarningsAsErrors);
+    IO.mapOptional("HeaderFileExtensions", Options.HeaderFileExtensions);
+    IO.mapOptional("ImplementationFileExtensions",
+                   Options.ImplementationFileExtensions);
     IO.mapOptional("HeaderFilterRegex", Options.HeaderFilterRegex);
     IO.mapOptional("AnalyzeTemporaryDtors", Ignored); // deprecated
     IO.mapOptional("FormatStyle", Options.FormatStyle);
     IO.mapOptional("User", Options.User);
     IO.mapOptional("CheckOptions", Options.CheckOptions);
     IO.mapOptional("ExtraArgs", Options.ExtraArgs);
     IO.mapOptional("ExtraArgsBefore", Options.ExtraArgsBefore);
     IO.mapOptional("InheritParentConfig", Options.InheritParentConfig);
     IO.mapOptional("UseColor", Options.UseColor);
   }
 };
 
 } // namespace yaml
 } // namespace llvm
 
 namespace clang {
 namespace tidy {
 
 ClangTidyOptions ClangTidyOptions::getDefaults() {
   ClangTidyOptions Options;
   Options.Checks = "";
   Options.WarningsAsErrors = "";
+  Options.HeaderFileExtensions = {"h", "hh", "hpp", "hxx"};
+  Options.ImplementationFileExtensions = {"c", "cc", "cpp", "cxx"};
   Options.HeaderFilterRegex = "";
   Options.SystemHeaders = false;
   Options.FormatStyle = "none";
   Options.User = std::nullopt;
   for (const ClangTidyModuleRegistry::entry &Module :
        ClangTidyModuleRegistry::entries())
     Options.mergeWith(Module.instantiate()->getModuleOptions(), 0);
   return Options;
static void overrideValue(std::optional<T> &Dest, const std::optional<T> &Src) {
   if (Src)
     Dest = Src;
 }
 
 ClangTidyOptions &ClangTidyOptions::mergeWith(const ClangTidyOptions &Other,
                                               unsigned Order) {
   mergeCommaSeparatedLists(Checks, Other.Checks);
   mergeCommaSeparatedLists(WarningsAsErrors, Other.WarningsAsErrors);
+  overrideValue(HeaderFileExtensions, Other.HeaderFileExtensions);
+  overrideValue(ImplementationFileExtensions,
+                Other.ImplementationFileExtensions);
   overrideValue(HeaderFilterRegex, Other.HeaderFilterRegex);
   overrideValue(SystemHeaders, Other.SystemHeaders);
   overrideValue(FormatStyle, Other.FormatStyle);
   overrideValue(User, Other.User);
   overrideValue(UseColor, Other.UseColor);
   mergeVectors(ExtraArgs, Other.ExtraArgs);
   mergeVectors(ExtraArgsBefore, Other.ExtraArgsBefore);
 

clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp

Configuration files:
   file. If InheritParentConfig is true in a config file, the configuration file
   in the parent directory (if any exists) will be taken and current config file
   will be applied on top of the parent one. If any configuration options have
   a corresponding command-line option, 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
+    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'
     ...
 
 )");
 
 const char DefaultChecks[] = // Enable these checks by default:
     "clang-diagnostic-*,"    //   * compiler diagnostics

 Apply suggested fixes even if compilation
 errors were found. If compiler errors have
 attached fix-its, clang-tidy will apply them as
 well.
 )"),
                                cl::init(false), cl::cat(ClangTidyCategory));
 
 static cl::opt<bool> FixNotes("fix-notes", cl::desc(R"(
-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 
+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.
 )"),
                               cl::init(false), cl::cat(ClangTidyCategory));
 
 static cl::opt<std::string> FormatStyle("format-style", cl::desc(R"(
 Style for formatting code around applied fixes:
   - 'none' (default) turns off formatting
   - 'file' (literally 'file', not a placeholder)
if (Cur.contains('*')) {
       if (!Closest.empty())
         Output << "; did you mean '" << Closest << '\'';
       Output << VerifyConfigWarningEnd;
     }
   }
   return AnyInvalid;
 }
 
+static bool verifyFileExtensions(
+    const std::vector<std::string> &HeaderFileExtensions,
+    const std::vector<std::string> &ImplementationFileExtensions,
+    StringRef Source) {
+  bool AnyInvalid = false;
+  for (const auto &HeaderExtension : HeaderFileExtensions) {
+    for (const auto &ImplementationExtension : ImplementationFileExtensions) {
+      if (HeaderExtension == ImplementationExtension) {
+        AnyInvalid = true;
+        auto &Output = llvm::WithColor::warning(llvm::errs(), Source)
+                       << "HeaderFileExtension '" << HeaderExtension << '\''
+                       << " is the same as ImplementationFileExtension '"
+                       << ImplementationExtension << '\'';
+        Output << VerifyConfigWarningEnd;
+      }
+    }
+  }
+  return AnyInvalid;
+}
+
 int clangTidyMain(int argc, const char **argv) {
   llvm::InitLLVM X(argc, argv);
 
   // Enable help for -load option, if plugins are enabled.
   if (cl::Option *LoadOpt = cl::getRegisteredOptions().lookup("load"))
     LoadOpt->addCategory(ClangTidyCategory);
 
   llvm::Expected<CommonOptionsParser> OptionsParser =
std::vector<ClangTidyOptionsProvider::OptionsSource> RawOptions =
         OptionsProvider->getRawOptions(FileName);
     NamesAndOptions Valid =
         getAllChecksAndOptions(AllowEnablingAnalyzerAlphaCheckers);
     bool AnyInvalid = false;
     for (const auto &[Opts, Source] : RawOptions) {
       if (Opts.Checks)
         AnyInvalid |= verifyChecks(Valid.Names, *Opts.Checks, Source);
 
+      if (Opts.HeaderFileExtensions && Opts.ImplementationFileExtensions)
+        AnyInvalid |=
+            verifyFileExtensions(*Opts.HeaderFileExtensions,
+                                 *Opts.ImplementationFileExtensions, Source);
+
       for (auto Key : Opts.CheckOptions.keys()) {
         if (Valid.Options.contains(Key))
           continue;
         AnyInvalid = true;
         auto &Output = llvm::WithColor::warning(llvm::errs(), Source)
                        << "unknown check option '" << Key << '\'';
         llvm::StringRef Closest = closest(Key, Valid.Options);
         if (!Closest.empty())

clang-tools-extra/docs/ReleaseNotes.rst

 
 - Fix a minor bug in `add_new_check.py` to only traverse subdirectories
   when updating the list of checks in the documentation.
 
 - Deprecate the global configuration file option `AnalyzeTemporaryDtors`,
   which is no longer in use. The option will be fully removed in
   :program:`clang-tidy` version 18.
 
+- New global configuration file option `HeaderFileExtensions`, replacing the check-local
+  option of the same name.
+
+- New global configuration file option `ImplementationFileExtensions`, replacing the check-local
+  option of the same name.
+
 New checks
 ^^^^^^^^^^
 
 - New :doc:`bugprone-suspicious-realloc-usage
   <clang-tidy/checks/bugprone/suspicious-realloc-usage>` check.
 
   Finds usages of ``realloc`` where the return value is assigned to the
   same expression as passed to the first argument.

 
 Changes in existing checks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - Fixed a false positive in :doc:`bugprone-assignment-in-if-condition
   <clang-tidy/checks/bugprone/assignment-in-if-condition>` check when there
   was an assignement in a lambda found in the condition of an ``if``.
 
+- Deprecated check-local options `HeaderFileExtensions` and `ImplementationFileExtensions`
+  in :doc:`bugprone-dynamic-static-initializers
+  <clang-tidy/checks/bugprone/dynamic-static-initializers>` check.
+  Global options of the same name should be used instead.
+
 - Improved :doc:`bugprone-signal-handler
   <clang-tidy/checks/bugprone/signal-handler>` check. Partial
   support for C++14 signal handler rules was added. Bug report generation was
   improved.
 
+- Deprecated check-local options `HeaderFileExtensions` and `ImplementationFileExtensions`
+  in :doc:`bugprone-suspicious-include
+  <clang-tidy/checks/bugprone/suspicious-include>` check.
+  Global options of the same name should be used instead.
+
 - Fixed a false positive in :doc:`cppcoreguidelines-pro-type-member-init
   <clang-tidy/checks/cppcoreguidelines/pro-type-member-init>` when warnings
   would be emitted for uninitialized members of an anonymous union despite
   there being an initializer for one of the other members.
 
+- Deprecated check-local options `HeaderFileExtensions` and `ImplementationFileExtensions`
+  in :doc:`google-build-namespaces
+  <clang-tidy/checks/google/build-namespaces>` check.
+  Global options of the same name should be used instead.
+
+- Deprecated check-local options `HeaderFileExtensions` and `ImplementationFileExtensions`
+  in :doc:`google-global-names-in-headers
+  <clang-tidy/checks/google/global-names-in-headers>` check.
+  Global options of the same name should be used instead.
+
 - Fixed false positives in :doc:`google-objc-avoid-throwing-exception
   <clang-tidy/checks/google/objc-avoid-throwing-exception>` check for exceptions
   thrown by code emitted from macros in system headers.
 
+- Deprecated check-local options `HeaderFileExtensions` and `ImplementationFileExtensions`
+  in :doc:`llvm-header-guard
+  <clang-tidy/checks/llvm/header-guard>` check.
+  Global options of the same name should be used instead.
+
+- Deprecated check-local options `HeaderFileExtensions` and `ImplementationFileExtensions`
+  in :doc:`misc-definitions-in-headers
+  <clang-tidy/checks/misc/definitions-in-headers>` check.
+  Global options of the same name should be used instead.
+
 - Improved :doc:`misc-redundant-expression <clang-tidy/checks/misc/redundant-expression>`
   check.
 
   The check now skips concept definitions since redundant expressions still make sense
   inside them.
 
+- Deprecated check-local options `HeaderFileExtensions` and `ImplementationFileExtensions`
+  in :doc:`misc-unused-using-decls
+  <clang-tidy/checks/misc/misc-unused-using-decls>` check.
+  Global options of the same name should be used instead.
+
 - Improved :doc:`modernize-loop-convert <clang-tidy/checks/modernize/loop-convert>`
   to check for container functions ``begin``/``end`` etc on base classes of the container
   type, instead of only as direct members of the container type itself.
 
 - Improved :doc:`modernize-use-emplace <clang-tidy/checks/modernize/use-emplace>`
   check.
 
   The check now supports detecting inefficient invocations of ``push`` and

clang-tools-extra/docs/clang-tidy/checks/bugprone/suspicious-include.rst

.. code-block:: c++
   #include "Pterodactyl.h"    // OK, .h files tend not to have definitions.
   #include "Velociraptor.cpp" // Warning, filename is suspicious.
   #include_next <stdio.c>     // Warning, filename is suspicious.
 
 Options
 -------
 .. option:: HeaderFileExtensions
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`
+   version 18. Please use the global configuration option
+   `HeaderFileExtensions`.
+
    Default value: ``";h;hh;hpp;hxx"``
    A semicolon-separated list of filename extensions of header files (the
    filename extensions should not contain a "." prefix). For extension-less
    header files, use an empty string or leave an empty string between ";"
    if there are other filename extensions.
 
 .. option:: ImplementationFileExtensions
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`.
+   version 18. Please use the global configuration option
+   `ImplementationFileExtensions`.
+
    Default value: ``"c;cc;cpp;cxx"``
    Likewise, a semicolon-separated list of filename extensions of
    implementation files.

clang-tools-extra/docs/clang-tidy/checks/google/build-namespaces.rst

 
 Corresponding cpplint.py check name: `build/namespaces`.
 
 Options
 -------
 
 .. option:: HeaderFileExtensions
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`
+   version 18. Please use the global configuration option
+   `HeaderFileExtensions`.
+
    A comma-separated list of filename extensions of header files (the filename
    extensions should not include "." prefix). Default is "h,hh,hpp,hxx".
    For header files without an extension, use an empty string (if there are no
    other desired extensions) or leave an empty element in the list. E.g.,
    "h,hh,hpp,hxx," (note the trailing comma).

clang-tools-extra/docs/clang-tidy/checks/google/global-names-in-headers.rst

 .. title:: clang-tidy - google-global-names-in-headers
 
 google-global-names-in-headers
 ==============================
 
 Flag global namespace pollution in header files. Right now it only triggers on
 ``using`` declarations and directives.
 
 The relevant style guide section is
 https://google.github.io/styleguide/cppguide.html#Namespaces.
 
 Options
 -------
 
 .. option:: HeaderFileExtensions
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`
+   version 18. Please use the global configuration option
+   `HeaderFileExtensions`.
+
    A comma-separated list of filename extensions of header files (the filename
    extensions should not contain "." prefix). Default is "h".
    For header files without an extension, use an empty string (if there are no
    other desired extensions) or leave an empty element in the list. E.g.,
    "h,hh,hpp,hxx," (note the trailing comma).

clang-tools-extra/docs/clang-tidy/checks/llvm/header-guard.rst

 .. title:: clang-tidy - llvm-header-guard
 
 llvm-header-guard
 =================
 
 Finds and fixes header guards that do not adhere to LLVM style.
 
 Options
 -------
 
 .. option:: HeaderFileExtensions
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`
+   version 18. Please use the global configuration option
+   `HeaderFileExtensions`.
+
    A comma-separated list of filename extensions of header files (the filename
    extensions should not include "." prefix). Default is "h,hh,hpp,hxx".
    For header files without an extension, use an empty string (if there are no
    other desired extensions) or leave an empty element in the list. E.g.,
    "h,hh,hpp,hxx," (note the trailing comma).

clang-tools-extra/docs/clang-tidy/checks/misc/definitions-in-headers.rst

.. code-block:: c++
    template <class T>
    constexpr T pi = T(3.1415926L);
 
 Options
 -------
 
 .. option:: HeaderFileExtensions
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`
+   version 18. Please use the global configuration option
+   `HeaderFileExtensions`.
+
    A comma-separated list of filename extensions of header files (the filename
    extensions should not include "." prefix). Default is "h,hh,hpp,hxx".
    For header files without an extension, use an empty string (if there are no
    other desired extensions) or leave an empty element in the list. E.g.,
    "h,hh,hpp,hxx," (note the trailing comma).
 
 .. option:: UseHeaderFileExtension
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`
+   version 18. The check will unconditionally use the global option
+   `HeaderFileExtensions`.
+
    When `true`, the check will use the file extension to distinguish header
    files. Default is `true`.

clang-tools-extra/docs/clang-tidy/checks/misc/unused-using-decls.rst

.. code-block:: c++
   namespace n { class C; }
   using n::C;  // Never actually used.
 
 Options
 -------
 
 .. option:: HeaderFileExtensions
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`
+   version 18. Please use the global configuration option
+   `HeaderFileExtensions`.
+
    A semicolon-separated list of filename extensions of header files (the filename
    extensions should not include "." prefix). Default is "h,hh,hpp,hxx".
    For extension-less header files, use an empty string or leave an
    empty string between "," if there are other filename extensions.

clang-tools-extra/docs/clang-tidy/checks/misc/use-anonymous-namespace.rst

namespace {
     int x;
   } // namespace
 
 Options
 -------
 
 .. option:: HeaderFileExtensions
 
+   Note: this option is deprecated, it will be removed in :program:`clang-tidy`
+   version 18. Please use the global configuration option
+   `HeaderFileExtensions`.
+
    A semicolon-separated list of filename extensions of header files (the filename
    extensions should not include "." prefix). Default is ";h;hh;hpp;hxx".
    For extension-less header files, using an empty string or leaving an
    empty string between ";" if there are other filename extensions.
 
 [1] `Undeprecating static <https://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1012>`_

clang-tools-extra/docs/clang-tidy/index.rst

--checks=<string>              -
                                      file, if any.
     --config=<string>              -
                                      Specifies a configuration in YAML/JSON format:
                                        -config="{Checks: '*',
                                                  CheckOptions: {x, y}}"
                                      When the value is empty, clang-tidy will
                                      attempt to find a file named .clang-tidy for
                                      each source file in its parent directories.
-    --config-file=<string>         - 
+    --config-file=<string>         -
                                     Specify the path of .clang-tidy or custom config file:
                                       e.g. --config-file=/some/path/myTidyConfigFile
                                     This option internally works exactly the same way as
                                       --config option after reading specified config file.
                                     Use either --config-file or --config, not both.
     --dump-config                  -
                                      Dumps configuration in the YAML format to
                                      stdout. This option can be used along with a
--quiet                        -
                                      printing statistics about ignored warnings and
                                      warnings treated as errors if the respective
                                      options are specified.
     --store-check-profile=<prefix> -
                                      By default 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.
-    --use-color                    - 
+    --use-color                    -
                                     Use 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
                                     .clang-tidy file, if any.
     --verify-config                -
                                      Check the config files to ensure each check and
                                      option is recognized.
Configuration files:
     file. If InheritParentConfig is true in a config file, the configuration file
     in the parent directory (if any exists) will be taken and current config file
     will be applied on top of the parent one. If any configuration options have
     a corresponding command-line option, 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
+      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'
       ...
 
 .. _clang-tidy-nolint:
 
 Suppressing Undesired Diagnostics
 =================================

clang-tools-extra/test/clang-tidy/infrastructure/verify-config.cpp

 // RUN: clang-tidy -verify-config --config='' | FileCheck %s -check-prefix=CHECK-VERIFY-OK
 // CHECK-VERIFY-OK: No config errors detected.
 
 // RUN: not clang-tidy -verify-config \
 // RUN: --checks='-*,bad*glob,llvm*,llvm-includeorder,my-made-up-check' --config='{Checks: "readability-else-after-ret", \
+// RUN: HeaderFileExtensions: ["h", "hh", "hpp"], \
+// RUN: ImplementationFileExtensions: ["c", "cc", "hpp"], \
 // RUN: CheckOptions: [{key: "IgnoreMacros", value: "true"}, \
 // RUN:                {key: "StriceMode", value: "true"}, \
 // RUN:                {key: modernize-lop-convert.UseCxx20ReverseRanges, value: true} \
 // RUN:               ]}' 2>&1 | FileCheck %s \
 // RUN: -check-prefix=CHECK-VERIFY -implicit-check-not='{{warning|error}}:'
 
 // CHECK-VERIFY-DAG: command-line option '-config': warning: unknown check 'readability-else-after-ret'; did you mean 'readability-else-after-return' [-verify-config]
 // CHECK-VERIFY-DAG: command-line option '-config': warning: unknown check option 'modernize-lop-convert.UseCxx20ReverseRanges'; did you mean 'modernize-loop-convert.UseCxx20ReverseRanges' [-verify-config]
 // CHECK-VERIFY-DAG: command-line option '-config': warning: unknown check option 'StriceMode'; did you mean 'StrictMode' [-verify-config]
+// CHECK-VERIFY-DAG: command-line option '-config': warning: HeaderFileExtension 'hpp' is the same as ImplementationFileExtension 'hpp' [-verify-config]
 // CHECK-VERIFY: command-line option '-checks': warning: check glob 'bad*glob' doesn't match any known check [-verify-config]
 // CHECK-VERIFY: command-line option '-checks': warning: unknown check 'llvm-includeorder'; did you mean 'llvm-include-order' [-verify-config]
 // CHECK-VERIFY: command-line option '-checks': warning: unknown check 'my-made-up-check' [-verify-config]

clang-tools-extra/unittests/clang-tidy/ClangTidyOptionsTest.cpp

TEST(ParseLineFilter, ValidFilter) {
   EXPECT_EQ("file3.cc", Options.LineFilter[2].Name);
   EXPECT_EQ(1u, Options.LineFilter[2].LineRanges.size());
   EXPECT_EQ(100u, Options.LineFilter[2].LineRanges[0].first);
   EXPECT_EQ(1000u, Options.LineFilter[2].LineRanges[0].second);
 }
 
 TEST(ParseConfiguration, ValidConfiguration) {
   llvm::ErrorOr<ClangTidyOptions> Options =
-      parseConfiguration(llvm::MemoryBufferRef("Checks: \"-*,misc-*\"\n"
-                                               "HeaderFilterRegex: \".*\"\n"
-                                               "AnalyzeTemporaryDtors: true\n"
-                                               "User: some.user",
-                                               "Options"));
+      parseConfiguration(llvm::MemoryBufferRef(
+          "Checks: \"-*,misc-*\"\n"
+          "HeaderFileExtensions: [\"h\",\"hh\",\"hpp\",\"hxx\"]\n"
+          "ImplementationFileExtensions: [\"c\",\"cc\",\"cpp\",\"cxx\"]\n"
   EXPECT_TRUE(!!Options);
   EXPECT_EQ("-*,misc-*", *Options->Checks);
+  EXPECT_EQ(std::vector<std::string>({"h", "hh", "hpp", "hxx"}),
+            *Options->HeaderFileExtensions);
+  EXPECT_EQ(std::vector<std::string>({"c", "cc", "cpp", "cxx"}),
+            *Options->ImplementationFileExtensions);
   EXPECT_EQ(".*", *Options->HeaderFilterRegex);
   EXPECT_EQ("some.user", *Options->User);
 }
 
 TEST(ParseConfiguration, ChecksSeparatedByNewlines) {
   auto MemoryBuffer = llvm::MemoryBufferRef("Checks: |\n"
                                             "  -*,misc-*\n"
                                             "  llvm-*\n"
                                             "  -clang-*,\n"
                                             "  google-*",
                                             "Options");
 
   auto Options = parseConfiguration(MemoryBuffer);
 
   EXPECT_TRUE(!!Options);
   EXPECT_EQ("-*,misc-*\nllvm-*\n-clang-*,\ngoogle-*\n", *Options->Checks);
 }
 
 TEST(ParseConfiguration, MergeConfigurations) {
   llvm::ErrorOr<ClangTidyOptions> Options1 =
       parseConfiguration(llvm::MemoryBufferRef(R"(
       Checks: "check1,check2"
+      HeaderFileExtensions: ["h","hh"]
+      ImplementationFileExtensions: ["c","cc"]
       HeaderFilterRegex: "filter1"
       AnalyzeTemporaryDtors: true
       User: user1
       ExtraArgs: ['arg1', 'arg2']
       ExtraArgsBefore: ['arg-before1', 'arg-before2']
       UseColor: false
   )",
                                                "Options1"));
   ASSERT_TRUE(!!Options1);
   llvm::ErrorOr<ClangTidyOptions> Options2 =
       parseConfiguration(llvm::MemoryBufferRef(R"(
       Checks: "check3,check4"
+      HeaderFileExtensions: ["hpp","hxx"]
+      ImplementationFileExtensions: ["cpp","cxx"]
       HeaderFilterRegex: "filter2"
       AnalyzeTemporaryDtors: false
       User: user2
       ExtraArgs: ['arg3', 'arg4']
       ExtraArgsBefore: ['arg-before3', 'arg-before4']
       UseColor: true
   )",
                                                "Options2"));
   ASSERT_TRUE(!!Options2);
   ClangTidyOptions Options = Options1->merge(*Options2, 0);
   EXPECT_EQ("check1,check2,check3,check4", *Options.Checks);
+  EXPECT_EQ(std::vector<std::string>({"hpp", "hxx"}),
+            *Options.HeaderFileExtensions);
+  EXPECT_EQ(std::vector<std::string>({"cpp", "cxx"}),
+            *Options.ImplementationFileExtensions);
   EXPECT_EQ("filter2", *Options.HeaderFilterRegex);
   EXPECT_EQ("user2", *Options.User);
   ASSERT_TRUE(Options.ExtraArgs.has_value());
   EXPECT_EQ("arg1,arg2,arg3,arg4", llvm::join(Options.ExtraArgs->begin(),
                                               Options.ExtraArgs->end(), ","));
   ASSERT_TRUE(Options.ExtraArgsBefore.has_value());
   EXPECT_EQ("arg-before1,arg-before2,arg-before3,arg-before4",
             llvm::join(Options.ExtraArgsBefore->begin(),