# Cpp Include Sorter

> Automatically sorts C/C++ header files (#include statements) with full support for conditional compilation blocks. Use when Claude needs to organize

- Skill: `openharmonyinsight/cpp-include-sorter` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add openharmonyinsight/cpp-include-sorter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openharmonyinsight/cpp-include-sorter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: openharmonyinsight (https://skillmd.com/u/openharmonyinsight)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openharmonyinsight/cpp-include-sorter

---


# C/C++ Include Sorter

Automatically sorts `#include` statements in C/C++ source files with intelligent handling of conditional compilation blocks.

## 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
```

## Sorting Rules

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

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

### 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

## 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"
```

## 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

## 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

## Verification

After sorting, verify:
1. All `#ifdef` blocks contain same number of headers as before
2. Corresponding header has complete path (not shortened)
3. Total include count unchanged
4. Comments preserved

Use `git diff` to compare before/after:
```bash
git diff <file.cpp> | grep "^[-+]" | grep "include"
```