[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