clang-format

clang-format 配置

使用开箱即用的模板、集成脚本和全面的参考文档配置 clang-format 代码格式化工具。

用途

此技能提供 clang-format 配置任务的操作流程：

• 根据成熟模板创建新的 .clang-format 文件
• 分析现有代码风格并生成匹配的配置
• 使用附带的脚本设置编辑器和 git 集成
• 使用参考文档排查格式化行为问题

按触发类型路由工作流

触发后，根据触发类型选择相应的工作流：

触发器 1：明确提及 clang-format → 如果用户询问特定选项：查阅 references/01-09.md 中的相关类别 → 如果用户需要完整参考资料：引导至 references/complete/clang-format-style-options.md → 如果用户询问 CLI 用法：参考 references/cli-usage.md

触发器 2：请求分析代码风格 → 按照下方“分析现有代码风格”工作流 → 系统地检查代码示例（大括号→缩进→间距→换行→对齐）→ 将模式映射到 assets/configs/ 中最接近的模板 → 将初始配置假设生成为临时配置文件 "/tmp/<reponame>/hypothesis.clang-format" → 验证影响：在 3-5 个有代表性的示例上运行 clang-format --style="/tmp/<repo_name>/hypothesis_<number>.clang-format" file.cpp | diff - file.cpp → 使用加权评分衡量影响：• 指标 1：行数变化（新增/删除的行数）- 权重 10 • 指标 2：行内空白变化（现有行内的间距）- 权重 1 • 影响分数 =（行数变化 × 10）+（空白变化 × 1）• 分数越低，对变基冲突、后续 git-diff 分析以及合并请求变更审查的影响越小，配置越好 → 迭代：调整影响最大的配置选项，重新测试并比较分数 → 重复此过程，直到在保持风格一致性的同时达到可实现的最低分数 → 向用户报告：提供胜出的配置，并包含：• 最终影响分数及其细分（行变化与空白变化）• 显示所有已测试假设及其分数的比较表 • 展示将发生哪些变化的示例 diff 片段，以及供用户自行对选定文件进行测试的命令。 • 所选配置的理由 → 在最终确定配置前等待用户批准 → 只有在获得批准后：提供最终配置文件

触发器 3：配置文件操作 → 如果要新建：按照“根据模板创建新配置”工作流 → 如果要修改现有配置：读取当前配置，确定所需变更，并查阅相关类别指南 → 如果要根据代码生成：使用触发器 2 工作流（代码风格分析）

触发器 4：调查格式化行为 → 按照下方“排查格式化问题”工作流 → 使用 --dump-config 验证配置检测情况 → 确定受影响的类别，并查阅 references/0X.md 指南 → 使用最小配置测试单独选项

触发器 5：询问风格选项 → 将问题映射到类别：大括号→03、缩进→04、间距→05、对齐→01、换行→02 → 参考 references/ 中的具体类别指南 → 如适用，提供 quick-reference.md 中的示例

触发器 6：请求尽量减少改动 → 使用“分析现有代码风格”工作流来匹配现有模式 → 强调从最接近的模板开始，以尽量减少改动 → 在应用到整个项目之前，先在有代表性的示例上进行测试 → 记录保留了哪些模式，以及规范化了哪些模式

附带资源

配置模板（assets/configs/）

七个可直接使用的 .clang-format 模板，针对常见场景进行了优化：

• google-cpp-modified.clang-format - Google C++ 风格，使用 4 个空格缩进，列宽限制为 120
• linux-kernel.clang-format - Linux 内核编码规范（制表符、K&R 大括号）
• microsoft-visual-studio.clang-format - Microsoft/Visual Studio 约定
• modern-cpp17-20.clang-format - 现代 C++17/20 风格，采用当代惯用写法
• compact-dense.clang-format - 适用于空间受限环境的紧凑风格
• readable-spacious.clang-format - 优先考虑可读性的宽松风格
• multi-language.clang-format - 多语言配置（C++、JavaScript、Java）

何时使用模板：启动新项目、建立团队规范，或快速测试格式化方案。

集成脚本（assets/integrations/）

三个编辑器和 Git 集成脚本：

• pre-commit - Git 钩子脚本，用于自动格式化暂存文件（适用于 pre-commit 或 prek 框架）
• vimrc-clang-format.vim - Vim 配置，用于保存时格式化
• emacs-clang-format.el - Emacs 配置，用于集成 clang-format

何时使用集成脚本：在开发工作流中设置自动格式化。

注意：pre-commit 钩子脚本同时适用于 pre-commit 框架（Python）和 prek（Rust 替代方案）。两个框架都使用 .pre-commit-config.yaml，语法相同。

参考文档（references/）

按类别整理的详细文档：

快速导航：

• index.md - 概览和文档中心
• quick-reference.md - 完整可用的配置及其说明
• cli-usage.md - 命令行用法、编辑器设置、CI/CD 集成

选项类别（01-09.md）：

1. 01-alignment.md - 声明、赋值和运算符的垂直对齐
2. 02-breaking.md - 换行和折行规则
3. 03-braces.md - 大括号位置风格（K&R、Allman、GNU 等）
4. 04-indentation.md - 缩进规则和特殊情况
5. 05-spacing.md - 控制运算符和关键字周围的空白
6. 06-includes.md - include/import 的组织和排序
7. 07-languages.md - C++、Java、JavaScript 的语言专属选项
8. 08-comments.md - 注释格式化和重新排版
9. 09-advanced.md - 惩罚系统、原始字符串格式化、实验性功能

完整参考（complete/）：

• clang-format-cli.md - 完整的命令行界面文档
• clang-format-style-options.md - 全部 194 个样式选项及示例

常见工作流

从模板创建新配置

创建新的 .clang-format 文件：

1. 确定需求（风格指南、团队偏好、语言）
2. 从 assets/configs/ 中选择最接近的模板
3. 将模板复制到项目根目录，命名为 .clang-format
4. 测试格式化：clang-format --dry-run file.cpp
5. 根据需要参考 references/01-09.md，自定义特定选项
6. 验证更改：clang-format file.cpp | diff - file.cpp

示例：

# Copy Google C++ template
cp assets/configs/google-cpp-modified.clang-format /path/to/project/.clang-format

# Test on sample file
clang-format --dry-run /path/to/project/src/main.cpp

# Apply if satisfied
clang-format -i /path/to/project/src/*.cpp

分析现有代码风格

生成与现有代码匹配的配置：

1. 检查代码样例，了解格式化模式
2. 确定关键特征：
   • 大括号位置 → 参考 references/03-braces.md
   • 缩进（空格/制表符、宽度）→ 参考 references/04-indentation.md
   • 空白（运算符、关键字）→ 参考 references/05-spacing.md
   • 换行（列宽限制、折行）→ 参考 references/02-breaking.md
   • 对齐模式 → 参考 references/01-alignment.md
3. 在 references/quick-reference.md 中找到最接近的基础风格
4. 从 assets/configs/ 中选用对应模板
5. 覆盖特定选项，使其符合观察到的模式
6. 在有代表性的代码样例上进行测试
7. 反复调整，直到格式与现有风格一致

在现有项目中引入 clang-format 时，此工作流可尽量减少仅涉及空白的更改。

设置编辑器集成

要在编辑器中启用保存时格式化：

Vim：

1. 将 assets/integrations/vimrc-clang-format.vim 的内容复制到 .vimrc
2. 重启 Vim 或加载配置
3. 保存任意 C/C++/Java 文件以触发格式化

Emacs：

1. 将 assets/integrations/emacs-clang-format.el 复制到 Emacs 配置中
2. 重启 Emacs 或执行配置
3. 保存任意受支持的文件以触发格式化

其他编辑器：请参阅 references/cli-usage.md，了解 VS Code、CLion 和其他编辑器的设置说明。

设置用于格式化的 Git Hook

选项 1：使用 pre-commit/prek 框架（推荐）：

在 .pre-commit-config.yaml 中配置：

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v19.1.7
    hooks:
      - id: clang-format

然后安装：pre-commit install 或 prek install

选项 2：手动设置 Git Hook：

1. 将 assets/integrations/pre-commit 复制到 .git/hooks/pre-commit
2. 设置为可执行：chmod +x .git/hooks/pre-commit
3. 暂存并提交更改以进行测试

此 Hook 只会格式化已暂存的文件，并保留未暂存的更改。

排查格式化问题

格式化结果不符合预期时：

1. 验证配置检测：clang-format --dump-config file.cpp
2. 检查 references/cli-usage.md 中的命令选项
3. 确定受影响的格式化类别（大括号、间距、换行等）
4. 查阅 references/01-09.md 中相关类别的指南
5. 测试单独的选项：创建一个包含可疑选项的最小配置
6. 如需全面了解选项详情，请查看 references/complete/clang-format-style-options.md

设置 CI/CD 格式检查

要在持续集成中强制执行格式要求：

1. 查看 references/cli-usage.md 中的 CI 示例
2. 将 clang-format 检查添加到流水线中：

   # Check formatting without modifying files
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. 配置为在存在格式违规时使构建失败
4. 为贡献者说明格式要求

核心概念

基础样式：预定义配置（LLVM、Google、Chromium、Mozilla、WebKit、Microsoft、GNU）可作为起点。设置 BasedOnStyle: Google，然后覆盖特定选项。

多语言支持：使用 Language: 键在单个文件中分别配置不同语言。示例请参阅 assets/configs/multi-language.clang-format。

惩罚机制：clang-format 使用惩罚值在不同格式化方案之间进行选择。惩罚值越高，越不倾向于采用特定方案。详情请参阅 references/09-advanced.md。

渐进式优化：从最符合需求的模板开始，然后逐步自定义。经常使用有代表性的代码示例进行测试。

测试配置

# Preview changes without modifying file
clang-format --dry-run file.cpp

# Show diff of proposed changes
clang-format file.cpp | diff - file.cpp

# Apply formatting to file
clang-format -i file.cpp

# Format entire project
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# Check formatting in CI (fail on violations)
clang-format --dry-run --Werror src/**/*.{cpp,h}

导航策略

对于大多数任务，请按以下顺序进行：

1. 从模板开始：浏览 assets/configs/，查找可直接使用的配置
2. 快速参考：查看 references/quick-reference.md，获取附带说明的完整配置
3. 分类指南：查阅 references/01-09.md，了解特定选项类别
4. CLI 用法：参考 references/cli-usage.md，了解命令行和集成详情
5. 完整参考：使用 references/complete/，查阅详尽的选项文档

分析代码或排查问题时，先确定格式方面的问题（大括号、间距、对齐等），然后直接查看 references/ 中相关类别的指南。