gh-jamie-bitflight-claude-skills-development-skills/skills/clang-format/references/06-includes.md

Include Organization Options

← Prev: Spacing | Back to Index | Next: Languages →

Navigation: Alignment | Breaking | Braces | Indentation | Spacing | Includes | Languages | Comments | Advanced

Organize and sort include directives automatically.

Migration Note

Important: In Clang v22, SortIncludes has changed from a simple enum to a nested configuration structure:

• Old syntax (deprecated): SortIncludes: Never|CaseSensitive|CaseInsensitive
• New syntax:

  SortIncludes:
    Enabled: true/false
    IgnoreCase: true/false
    IgnoreExtension: true/false
  

Migration Guide:

• SortIncludes: Never → SortIncludes: { Enabled: false }
• SortIncludes: CaseSensitive → SortIncludes: { Enabled: true, IgnoreCase: false }
• SortIncludes: CaseInsensitive → SortIncludes: { Enabled: true, IgnoreCase: true }

The old values are deprecated but still supported for backward compatibility.

Enable Include Sorting

SortIncludes

Controls if and how clang-format will sort #includes.

Type: SortIncludesOptions (nested configuration) Suboptions:

• Enabled (bool) - If true, includes are sorted based on other suboptions. Replaces deprecated Never value (use Enabled: false instead).
• IgnoreCase (bool) - Whether includes are sorted case-insensitively. Replaces deprecated CaseSensitive and CaseInsensitive values (use IgnoreCase: false and IgnoreCase: true respectively).
• IgnoreExtension (bool) - When sorting includes in each block, only take file extensions into account if two includes compare equal otherwise.

Example:

IgnoreCase: false (replaces CaseSensitive):

#include "A/B.h"
#include "A/b.h"
#include "B/A.h"
#include "B/a.h"
#include "a/b.h"

IgnoreCase: true (replaces CaseInsensitive):

#include "A/B.h"
#include "A/b.h"
#include "a/b.h"
#include "B/A.h"
#include "B/a.h"

IgnoreExtension: true:

# include "A.h"
# include "A.inc"
# include "A-util.h"

IgnoreExtension: false:

# include "A-util.h"
# include "A.h"
# include "A.inc"

Configuration:

SortIncludes:
  Enabled: true
  IgnoreCase: false
  IgnoreExtension: false

Include Blocks

IncludeBlocks

How to organize include blocks.

Type: IncludeBlocksStyle Values:

• Preserve - Keep existing blocks
• Merge - Merge all includes into one block
• Regroup - Separate into blocks by category

Examples:

Preserve:

#include "b.h"

#include "a.h"
#include <lib/main.h>

Merge:

#include "a.h"
#include "b.h"
#include <lib/main.h>

Regroup:

#include "a.h"
#include "b.h"

#include <lib/main.h>

Include Categories

IncludeCategories

Define categories for organizing includes.

Type: List of IncludeCategories

Structure:

IncludeCategories:
  - Regex: "<[[:alnum:]]+>"
    Priority: 1
  - Regex: "<.*>"
    Priority: 2
  - Regex: ".*"
    Priority: 3

Fields:

• Regex - Regular expression to match include path
• Priority - Sort priority (lower numbers first)
• SortPriority - Optional separate sort priority
• CaseSensitive - Optional case sensitivity flag

Example Configuration:

IncludeBlocks: Regroup
IncludeCategories:
  # Main header (for .cpp files)
  - Regex: '^".*\.h"$'
    Priority: 1
    SortPriority: 1
  # Project headers
  - Regex: '^".*"$'
    Priority: 2
    SortPriority: 2
  # System headers
  - Regex: '^<.*\.h>$'
    Priority: 3
    SortPriority: 3
  # C++ standard library
  - Regex: "^<.*>$"
    Priority: 4
    SortPriority: 4

Result:

#include "myclass.h"

#include "project/helper.h"
#include "project/utils.h"

#include <stdio.h>
#include <stdlib.h>

#include <algorithm>
#include <vector>

Main Include Detection

IncludeIsMainRegex

Regex to identify main include file.

Type: String Default: ([-_](test|unittest))?$

Used to ensure the main header for a .cpp file sorts first.

Example:

For foo.cpp, these would be detected as main includes:

• foo.h
• foo_test.h
• foo-unittest.h

IncludeIsMainRegex: "([-_](test|unittest))?$"

IncludeIsMainSourceRegex

Additional regex for detecting source files.

Type: String

Example:

IncludeIsMainSourceRegex: "(_test)?$"

This helps clang-format recognize test files as valid source files.

Common Configurations

C++ with Standard Library Priority

SortIncludes:
  Enabled: true
  IgnoreCase: false
IncludeBlocks: Regroup
IncludeCategories:
  - Regex: '^".*\.h"'
    Priority: 1
  - Regex: '^".*'
    Priority: 2
  - Regex: '^<.*\.h>'
    Priority: 3
  - Regex: "^<.*"
    Priority: 4
IncludeIsMainRegex: "([-_](test|unittest))?$"

Result:

// main.cpp
#include "main.h"

#include "project/module.h"

#include <sys/types.h>

#include <iostream>
#include <vector>

Google C++ Style

SortIncludes:
  Enabled: true
  IgnoreCase: false
IncludeBlocks: Regroup
IncludeCategories:
  - Regex: '^<ext/.*\.h>'
    Priority: 2
    SortPriority: 0
  - Regex: '^<.*\.h>'
    Priority: 1
    SortPriority: 1
  - Regex: "^<.*"
    Priority: 2
    SortPriority: 2
  - Regex: ".*"
    Priority: 3
    SortPriority: 3
IncludeIsMainRegex: "([-_](test|unittest))?$"

LLVM Style

SortIncludes:
  Enabled: true
  IgnoreCase: false
IncludeBlocks: Regroup
IncludeCategories:
  - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
    Priority: 2
    SortPriority: 0
  - Regex: '^(<|"(gtest|gmock|isl|json)/)'
    Priority: 3
  - Regex: ".*"
    Priority: 1
IncludeIsMainRegex: "(Test)?$"
IncludeIsMainSourceRegex: ""

Mozilla Style

SortIncludes:
  Enabled: true
  IgnoreCase: true
IncludeBlocks: Regroup
IncludeCategories:
  - Regex: '^".*\.h"'
    Priority: 1
  - Regex: '^<.*\.h>'
    Priority: 2
  - Regex: "^<.*"
    Priority: 3
  - Regex: ".*"
    Priority: 4

Simple Three-Tier

SortIncludes:
  Enabled: true
  IgnoreCase: false
IncludeBlocks: Regroup
IncludeCategories:
  # Local headers
  - Regex: '^"'
    Priority: 1
  # System headers
  - Regex: '^<.*\.h>'
    Priority: 2
  # C++ standard library
  - Regex: "^<"
    Priority: 3

Result:

#include "local.h"

#include <stdlib.h>
#include <sys/types.h>

#include <iostream>
#include <string>

Tips

1. Test Thoroughly: Include sorting can be tricky; test on your entire codebase
2. Main Header First: Configure IncludeIsMainRegex to match your naming conventions
3. Category Priority: Lower priority numbers sort first
4. Regex Matching: Test your regex patterns carefully; they must match the full include path
5. Case Sensitivity: Match your filesystem's case sensitivity
6. Block Separation: Use Regroup for visual organization
7. Gradual Adoption: Consider Preserve initially, then migrate to Regroup

Disabling Sorting

To disable include sorting for specific sections:

// clang-format off
#include "z.h"
#include "a.h"
// clang-format on

Or globally:

SortIncludes:
  Enabled: false

Note: SortIncludes: Never is deprecated, use Enabled: false instead.

See Also

• CLI Usage - Command-line options including --sort-includes
• Comments & Misc - Comment-related options
• Languages - Language-specific settings
• Full Style Options Reference

---

← Prev: Spacing | Back to Index | Next: Languages →