[clang] [clang-format] IBS_RegroupByDirectory to add breaks between top level directories (PR #233877)
via cfe-commits
cfe-commits at lists.llvm.org
Wed Nov 4 01:48:39 PST 2026
https://github.com/matthew-j-code updated https://github.com/llvm/llvm-project/pull/233877
>From 8da6ce1a98fc945f958b9a3d4ef78c167854da9e Mon Sep 17 00:00:00 2001
From: "Eric J. Bringley" <eric.bringley at siemens.com>
Date: Wed, 7 Oct 2026 17:45:11 +0100
Subject: [PATCH 1/3] IBS_RegroupByDirectory to add breaks between top level
directories
When a project wants to visually separate the projects' includes by folders, they would need to curate a list of IncludeCategories per folder. This provides an alternative where they can capture multiple folders with a single IncludeCategory regex and still insert breaks between changes in top-level directory.
```
/// Foo.cpp
#include "Foo.h"
#include "A/a.h"
#include "B/b3.h"
#include "B/b2.h"
#include "C/Bar.h"
#include "C/BarBar.h"
#include "AThirdPartyLibrary/TPL.h"
```
would become
```
/// Foo.cpp
#include "Foo.h"
#include "A/a.h"
#include "B/b2.h"
#include "B/b3.h"
#include "C/Bar.h"
#Include "C/BarBar.h"
#include "AThirdPartyLibrary/TPL.h"
```
using two categories
```
IncludeCategories:
- Regex: 'AThirdPartyLibrary/.*\.h'
Priority: 4
SortPriority: 0
CaseSensitive: false
- Regex: '.*/.*\.h'
Priority: 3
SortPriority: 0
CaseSensitive: false
```
---
clang/docs/ClangFormatStyleOptions.md | 12 +++++
clang/docs/ReleaseNotes.md | 2 +
.../clang/Tooling/Inclusions/IncludeStyle.h | 10 ++++
clang/lib/Format/Format.cpp | 23 +++++++-
clang/lib/Tooling/Inclusions/IncludeStyle.cpp | 2 +
clang/unittests/Format/ConfigParseTest.cpp | 9 ++++
clang/unittests/Format/SortIncludesTest.cpp | 53 +++++++++++++++++++
7 files changed, 110 insertions(+), 1 deletion(-)
diff --git a/clang/docs/ClangFormatStyleOptions.md b/clang/docs/ClangFormatStyleOptions.md
index af81eed1c6f138..e85311c26d2312 100644
--- a/clang/docs/ClangFormatStyleOptions.md
+++ b/clang/docs/ClangFormatStyleOptions.md
@@ -4649,6 +4649,18 @@ the configuration (without a prefix: `Auto`).
#include "a.h" #include <lib/main.h>
```
+ - `IBS_RegroupByDirectory` (in configuration: `RegroupByDirectory`)
+ Merge multiple `#include` blocks together and sort as one.
+ It's first grouped by category priority (defined in clang-format
+ config), then by top-level directory within each category.
+
+ ```c++
+ #include "b/b.h" into #include "a/a.h"
+ #include "a/b.h" #include "a/b.h"
+ #include "a/a.h"
+ #include "b/b.h"
+ ```
+
(includecategories)=
diff --git a/clang/docs/ReleaseNotes.md b/clang/docs/ReleaseNotes.md
index 1723b7f78cc9d4..c0192869926386 100644
--- a/clang/docs/ReleaseNotes.md
+++ b/clang/docs/ReleaseNotes.md
@@ -1253,6 +1253,8 @@ features cannot lower the translation-unit ABI level;
### clang-format
+- Add `RegroupByDirectory` value to `IncludeBlocks` to group includes by
+ category priority and top-level directory.
- Add `SpacesInBlockComments` option to control spacing after `/*` and
before `*/` in ordinary block comments.
- Add `AfterRequiresExpression` sub-option of `BraceWrapping` to wrap the
diff --git a/clang/include/clang/Tooling/Inclusions/IncludeStyle.h b/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
index 14273324b128aa..2df43ab5bab3b3 100644
--- a/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
+++ b/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
@@ -46,6 +46,16 @@ struct IncludeStyle {
/// #include "a.h" #include <lib/main.h>
/// \endcode
IBS_Regroup,
+ /// Merge multiple `#include` blocks together and sort as one.
+ /// It's first grouped by category priority (defined in clang-format
+ /// config), then by top-level directory within each category.
+ /// \code
+ /// #include "b/b.h" into #include "a/a.h"
+ /// #include "a/b.h" #include "a/b.h"
+ /// #include "a/a.h"
+ /// #include "b/b.h"
+ /// \endcode
+ IBS_RegroupByDirectory,
};
/// Dependent on the value, multiple `#include` blocks can be sorted
diff --git a/clang/lib/Format/Format.cpp b/clang/lib/Format/Format.cpp
index c4baf8002c274d..6ab7de3b2d1ffa 100644
--- a/clang/lib/Format/Format.cpp
+++ b/clang/lib/Format/Format.cpp
@@ -3789,6 +3789,19 @@ static void sortCppIncludes(const FormatStyle &Style,
Indices.end());
int CurrentCategory = Includes.front().Category;
+ const auto TopLevelDirectory = [](StringRef Filename) {
+ Filename = Filename.drop_front(); // Strip leading '"' or '<'.
+ const size_t SlashPos = Filename.find('/');
+ return SlashPos == StringRef::npos ? StringRef()
+ : Filename.take_front(SlashPos);
+ };
+ StringRef CurrentDirectory = TopLevelDirectory(Includes.front().Filename);
+ const auto DirectoryChanged = [&](StringRef Filename) {
+ const StringRef Directory = TopLevelDirectory(Filename);
+ return Style.SortIncludes.IgnoreCase
+ ? !CurrentDirectory.equals_insensitive(Directory)
+ : CurrentDirectory != Directory;
+ };
// If the #includes are out of order, we generate a single replacement fixing
// the entire block. Otherwise, no replacement is generated.
@@ -3810,12 +3823,18 @@ static void sortCppIncludes(const FormatStyle &Style,
tooling::IncludeStyle::IBS_Regroup &&
CurrentCategory != Includes[Index].Category) {
result += "\n";
+ } else if (Style.IncludeStyle.IncludeBlocks ==
+ tooling::IncludeStyle::IBS_RegroupByDirectory &&
+ (CurrentCategory != Includes[Index].Category ||
+ DirectoryChanged(Includes[Index].Filename))) {
+ result += "\n";
}
}
result += Includes[Index].Text;
if (Cursor && CursorIndex == Index)
*Cursor = IncludesBeginOffset + result.size() - CursorToEOLOffset;
CurrentCategory = Includes[Index].Category;
+ CurrentDirectory = TopLevelDirectory(Includes[Index].Filename);
}
if (Cursor && *Cursor >= IncludesEndOffset)
@@ -3911,7 +3930,9 @@ tooling::Replacements sortCppIncludes(const FormatStyle &Style, StringRef Code,
Trimmed.empty() &&
(Style.IncludeStyle.IncludeBlocks == tooling::IncludeStyle::IBS_Merge ||
Style.IncludeStyle.IncludeBlocks ==
- tooling::IncludeStyle::IBS_Regroup);
+ tooling::IncludeStyle::IBS_Regroup ||
+ Style.IncludeStyle.IncludeBlocks ==
+ tooling::IncludeStyle::IBS_RegroupByDirectory);
bool MergeWithNextLine = Trimmed.ends_with("\\");
if (!FormattingOff && !MergeWithNextLine) {
diff --git a/clang/lib/Tooling/Inclusions/IncludeStyle.cpp b/clang/lib/Tooling/Inclusions/IncludeStyle.cpp
index 05dfb50589de0c..a89ea6843ceccc 100644
--- a/clang/lib/Tooling/Inclusions/IncludeStyle.cpp
+++ b/clang/lib/Tooling/Inclusions/IncludeStyle.cpp
@@ -26,6 +26,8 @@ void ScalarEnumerationTraits<IncludeStyle::IncludeBlocksStyle>::enumeration(
IO.enumCase(Value, "Preserve", IncludeStyle::IBS_Preserve);
IO.enumCase(Value, "Merge", IncludeStyle::IBS_Merge);
IO.enumCase(Value, "Regroup", IncludeStyle::IBS_Regroup);
+ IO.enumCase(Value, "RegroupByDirectory",
+ IncludeStyle::IBS_RegroupByDirectory);
}
void ScalarEnumerationTraits<IncludeStyle::MainIncludeCharDiscriminator>::
diff --git a/clang/unittests/Format/ConfigParseTest.cpp b/clang/unittests/Format/ConfigParseTest.cpp
index ab160db1e9f13c..6222d99af117d2 100644
--- a/clang/unittests/Format/ConfigParseTest.cpp
+++ b/clang/unittests/Format/ConfigParseTest.cpp
@@ -1167,6 +1167,15 @@ TEST(ConfigParseTest, ParsesConfiguration) {
WhitespaceSensitiveMacros,
std::vector<std::string>({"STRINGIZE", "ASSERT"}));
+ CHECK_PARSE("IncludeBlocks: Merge", IncludeStyle.IncludeBlocks,
+ tooling::IncludeStyle::IBS_Merge);
+ CHECK_PARSE("IncludeBlocks: Regroup", IncludeStyle.IncludeBlocks,
+ tooling::IncludeStyle::IBS_Regroup);
+ CHECK_PARSE("IncludeBlocks: Preserve", IncludeStyle.IncludeBlocks,
+ tooling::IncludeStyle::IBS_Preserve);
+ CHECK_PARSE("IncludeBlocks: RegroupByDirectory", IncludeStyle.IncludeBlocks,
+ tooling::IncludeStyle::IBS_RegroupByDirectory);
+
Style.IncludeStyle.IncludeCategories.clear();
std::vector<tooling::IncludeStyle::IncludeCategory> ExpectedCategories = {
{"abc/.*", 2, 0, false}, {".*", 1, 0, true}};
diff --git a/clang/unittests/Format/SortIncludesTest.cpp b/clang/unittests/Format/SortIncludesTest.cpp
index ac2b227a9e2554..f353daddf11539 100644
--- a/clang/unittests/Format/SortIncludesTest.cpp
+++ b/clang/unittests/Format/SortIncludesTest.cpp
@@ -1655,6 +1655,59 @@ TEST_F(SortIncludesTest, FilesBeforeFoldersWithPriority) {
"#include \"utils.h\""));
}
+TEST_F(SortIncludesTest, RegroupByDirectory) {
+ Style.IncludeBlocks = tooling::IncludeStyle::IBS_RegroupByDirectory;
+ Style.IncludeCategories = {{"AThirdPartyLibrary/.*\\.h", 4, 0, false},
+ {".*/.*\\.h", 3, 0, false}};
+ verifyFormat("#include \"Foo.h\"\n"
+ "\n"
+ "#include \"A/a.h\"\n"
+ "\n"
+ "#include \"B/b2.h\"\n"
+ "#include \"B/b3.h\"\n"
+ "\n"
+ "#include \"C/Bar.h\"\n"
+ "#include \"C/BarBar.h\"\n"
+ "\n"
+ "#include \"AThirdPartyLibrary/TPL.h\"",
+ sort("#include \"Foo.h\"\n"
+ "\n"
+ "#include \"A/a.h\"\n"
+ "#include \"B/b3.h\"\n"
+ "#include \"B/b2.h\"\n"
+ "#include \"C/Bar.h\"\n"
+ "#include \"C/BarBar.h\"\n"
+ "\n"
+ "#include \"AThirdPartyLibrary/TPL.h\"",
+ "Foo.cpp"));
+}
+
+TEST_F(SortIncludesTest, RegroupByDirectoryMixedDelimitersAndCase) {
+ Style.IncludeBlocks = tooling::IncludeStyle::IBS_RegroupByDirectory;
+ Style.IncludeCategories = {{".*", 1, 0, false}};
+ verifyFormat("#include \"A/a.h\"\n"
+ "#include <A/b.h>\n"
+ "\n"
+ "#include <B/c.h>",
+ sort("#include <B/c.h>\n"
+ "#include <A/b.h>\n"
+ "#include \"A/a.h\""));
+
+ FmtStyle.SortIncludes.IgnoreCase = true;
+ verifyFormat("#include \"a//b.h\"\n"
+ "#include \"a/x.h\"\n"
+ "#include \"A/y.h\"\n"
+ "\n"
+ "#include \"B/z.h\"\n"
+ "\n"
+ "#include <z.h>",
+ sort("#include \"B/z.h\"\n"
+ "#include \"A/y.h\"\n"
+ "#include \"a/x.h\"\n"
+ "#include \"a//b.h\"\n"
+ "#include<z.h>"));
+}
+
} // end namespace
} // end namespace format
} // end namespace clang
>From c72a8dfa21878658bc3e73f57f96402f6d50479f Mon Sep 17 00:00:00 2001
From: "Jones, Matthew (DI SW SIM FRWK PLAT SIMFW HPC)"
<jones.matthew at siemens.com>
Date: Tue, 3 Nov 2026 01:47:37 -0800
Subject: [PATCH 2/3] [clang-format] Updated IncludeStyle descriptor
---
clang/docs/ClangFormatStyleOptions.md | 4 ++--
clang/include/clang/Tooling/Inclusions/IncludeStyle.h | 4 ++--
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/clang/docs/ClangFormatStyleOptions.md b/clang/docs/ClangFormatStyleOptions.md
index e85311c26d2312..f06f0a0db710f5 100644
--- a/clang/docs/ClangFormatStyleOptions.md
+++ b/clang/docs/ClangFormatStyleOptions.md
@@ -4651,8 +4651,8 @@ the configuration (without a prefix: `Auto`).
- `IBS_RegroupByDirectory` (in configuration: `RegroupByDirectory`)
Merge multiple `#include` blocks together and sort as one.
- It's first grouped by category priority (defined in clang-format
- config), then by top-level directory within each category.
+ It's first grouped by category priority, then by top-level directory
+ within each category.
```c++
#include "b/b.h" into #include "a/a.h"
diff --git a/clang/include/clang/Tooling/Inclusions/IncludeStyle.h b/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
index 2df43ab5bab3b3..1e0fef44b609dc 100644
--- a/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
+++ b/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
@@ -47,8 +47,8 @@ struct IncludeStyle {
/// \endcode
IBS_Regroup,
/// Merge multiple `#include` blocks together and sort as one.
- /// It's first grouped by category priority (defined in clang-format
- /// config), then by top-level directory within each category.
+ /// It's first grouped by category priority, then by top-level directory
+ /// within each category.
/// \code
/// #include "b/b.h" into #include "a/a.h"
/// #include "a/b.h" #include "a/b.h"
>From 502e936043f6a5677c174658b905f8e312acb4fc Mon Sep 17 00:00:00 2001
From: Matthew <matthew.arda at gmail.com>
Date: Wed, 4 Nov 2026 09:48:27 +0000
Subject: [PATCH 3/3] Apply suggestion from @HazardyKnusperkeks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: Björn Schäpers <github at hazardy.de>
---
clang/unittests/Format/SortIncludesTest.cpp | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang/unittests/Format/SortIncludesTest.cpp b/clang/unittests/Format/SortIncludesTest.cpp
index f353daddf11539..5e3d894f5b7039 100644
--- a/clang/unittests/Format/SortIncludesTest.cpp
+++ b/clang/unittests/Format/SortIncludesTest.cpp
@@ -1705,7 +1705,7 @@ TEST_F(SortIncludesTest, RegroupByDirectoryMixedDelimitersAndCase) {
"#include \"A/y.h\"\n"
"#include \"a/x.h\"\n"
"#include \"a//b.h\"\n"
- "#include<z.h>"));
+ "#include <z.h>"));
}
} // end namespace
More information about the cfe-commits
mailing list