cpp-include-sorter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

C/C++ Include Sorter

C/C++ 头文件排序工具

Automatically sorts

#include

statements in C/C++ source files with intelligent handling of conditional compilation blocks.

自动对C/C++源文件中的

#include

语句进行排序，智能处理条件编译块。

Quick Start

快速开始

Sort all

.cpp

files in a directory:

bash

python scripts/sort_includes.py <directory-path>

Preview changes without modifying files:

bash

python scripts/sort_includes.py <directory-path> --dry-run

对目录下所有

.cpp

文件进行排序：

bash

python scripts/sort_includes.py <directory-path>

预览更改而不修改文件：

bash

python scripts/sort_includes.py <directory-path> --dry-run

Sorting Rules

排序规则

Includes are organized into 3 categories with blank lines between each group:

Corresponding header - For
```
file.cpp
```
,
```
file.h
```
is placed first (prefers longest path if duplicates exist)
System headers - Headers with angle brackets
```
<>
```
(sorted alphabetically)
Local headers - Headers with double quotes
```
""
```
(sorted alphabetically)

头文件将被分为3个类别，每个类别之间用空行分隔：

对应头文件 - 对于
```
file.cpp
```
，
```
file.h
```
会被放在最前面（如果存在重复，优先选择最长路径的文件）
系统头文件 - 使用尖括号
```
<>
```
包裹的头文件（按字母顺序排序）
本地头文件 - 使用双引号
```
""
```
包裹的头文件（按字母顺序排序）

Conditional Compilation Blocks

条件编译块

#ifdef

#ifndef

#if defined

blocks are treated as units:

Blocks participate in global sorting based on their first include
Headers inside each block are also sorted (system headers first, then local headers)
Block structure (
```
#ifdef
```
...
```
#endif
```
) is preserved
```
#elif
```
and
```
#else
```
blocks are supported

#ifdef

#ifndef

#if defined

块会被视为一个整体：

块会根据其第一个头文件参与全局排序
每个块内部的头文件也会被排序（系统头文件在前，本地头文件在后）
块结构（
```
#ifdef
```
...
```
#endif
```
）会被保留
支持
```
#elif
```
和
```
#else
```
块

Example

示例

Before:

cpp

#include "common/rs_log.h"
#include "rs_trace.h"
#include <memory>
#ifdef RS_ENABLE_GPU
#include "feature/uifirst/rs_sub_thread_manager.h"
#include "feature/capture/rs_ui_capture_task_parallel.h"
#endif
#include "platform/common/rs_system_properties.h"

After:

cpp

#include "rs_trace.h"        // 1. Corresponding header (longest path preferred)

#include <memory>             // 2. System headers (alphabetical)

#include "common/rs_log.h"    // 3. Local headers (alphabetical)
#ifdef RS_ENABLE_GPU
#include "feature/capture/rs_ui_capture_task_parallel.h"
#include "feature/uifirst/rs_sub_thread_manager.h"
#endif
#include "platform/common/rs_system_properties.h"

排序前：

cpp

#include "common/rs_log.h"
#include "rs_trace.h"
#include <memory>
#ifdef RS_ENABLE_GPU
#include "feature/uifirst/rs_sub_thread_manager.h"
#include "feature/capture/rs_ui_capture_task_parallel.h"
#endif
#include "platform/common/rs_system_properties.h"

排序后：

cpp

#include "rs_trace.h"        // 1. 对应头文件（优先最长路径）

#include <memory>             // 2. 系统头文件（按字母顺序）

#include "common/rs_log.h"    // 3. 本地头文件（按字母顺序）
#ifdef RS_ENABLE_GPU
#include "feature/capture/rs_ui_capture_task_parallel.h"
#include "feature/uifirst/rs_sub_thread_manager.h"
#endif
#include "platform/common/rs_system_properties.h"

Features

功能特性

Duplicate include handling: When multiple includes with same filename but different paths exist (e.g.,
```
"file.h"
```
and
```
"path/to/file.h"
```
), the longest path is used as the corresponding header and placed first
Comment preservation: Inline comments (
```
// comment
```
) and preceding comments are preserved
Nested conditional blocks: Handles
```
#elif
```
and
```
#else
```
within
```
#ifdef
```
blocks
Validation: Verifies no headers are lost during sorting

重复头文件处理：当存在多个文件名相同但路径不同的头文件时（例如
```
"file.h"
```
和
```
"path/to/file.h"
```
），最长路径的文件会被作为对应头文件并放在最前面
注释保留：保留行内注释（
```
// comment
```
）和前置注释
嵌套条件块：支持处理
```
#ifdef
```
块内的
```
#elif
```
和
```
#else
```
验证功能：验证排序过程中没有丢失任何头文件

Script Reference

脚本参考

See

scripts/sort_includes.py

for implementation details.

Key functions:

```
extract_includes_with_ifdef()
```
- Parses includes and conditional blocks
```
sort_includes_with_ifdef()
```
- Sorts with 3-category rule
```
format_ifdef_block()
```
- Formats conditional blocks with sorted includes

查看

scripts/sort_includes.py

获取实现细节。

关键函数：

```
extract_includes_with_ifdef()
```
- 解析头文件和条件块
```
sort_includes_with_ifdef()
```
- 按照三类规则进行排序
```
format_ifdef_block()
```
- 格式化包含已排序头文件的条件块

Verification

验证

After sorting, verify:

All
```
#ifdef
```
blocks contain same number of headers as before
Corresponding header has complete path (not shortened)
Total include count unchanged
Comments preserved

Use

git diff

to compare before/after:

bash

git diff <file.cpp> | grep "^[-+]" | grep "include"

排序完成后，进行以下验证：

所有
```
#ifdef
```
块包含的头文件数量与排序前一致
对应头文件使用完整路径（未被缩短）
头文件总数保持不变
注释被完整保留

使用

git diff

对比排序前后的差异：

bash

git diff <file.cpp> | grep "^[-+]" | grep "include"