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/<repo_name>/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 分析和合并请求变更审查的影响越小 = 配置越好 → 迭代：调整针对最高影响设置的配置选项，重新测试，比较分数 → 重复直到在保持风格一致的前提下达到最低可实现分数 → 向用户报告：呈现获胜配置，包括： • 最终影响分数及细分（行数变化 vs 空白变化） • 比较表，显示所有测试过的假设及其分数 • 示例差异片段，显示将要更改的内容，并附上用户可以自行对其他文件进行测试的命令 • 所选配置的理由 → 等待用户批准后再最终确定配置 → 仅在批准后：提供最终配置文件

触发器 3：配置文件操作 → 如果是新建：执行“从模板创建新配置”工作流 → 如果是修改：读取当前配置，确定需要更改的内容，查阅相关分类指南 → 如果是从代码生成：使用触发器 2 的工作流（代码风格分析）

触发器 4：格式化行为调查 → 执行下面的“排查格式化问题”工作流 → 使用 --dump-config 验证配置检测 → 识别受影响的分类，查阅相应的 references/0X.md 指南 → 使用最小配置测试隔离选项

触发器 5：风格选项咨询 → 将问题映射到分类：大括号→03，缩进→04，间距→05，对齐→01，换行→02 → 在 references/ 中查阅特定分类指南 → 如果适用，提供 quick-reference.md 中的示例

触发器 6：最小影响请求 → 使用“分析现有代码风格”工作流匹配当前模式 → 强调从最接近的模板开始以最小化更改 → 在项目范围应用前对代表性样本进行测试 → 记录哪些模式被保留 vs 规范化

捆绑资源

配置模板 (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 - 包含/导入的组织与排序
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

示例：

# 复制 Google C++ 模板
cp assets/configs/google-cpp-modified.clang-format /path/to/project/.clang-format

# 在示例文件上测试
clang-format --dry-run /path/to/project/src/main.cpp

# 如果满意则应用
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 格式化钩子

选项 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 钩子：

1. 将 assets/integrations/pre-commit 复制到 .git/hooks/pre-commit
2. 赋予可执行权限：chmod +x .git/hooks/pre-commit
3. 通过暂存和提交更改来测试

该钩子仅格式化暂存文件，保留未暂存的更改。

排查格式化问题

当格式化产生意外结果时：

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 检查添加到流水线：

   # 检查格式化而不修改文件
   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。

渐进式优化：从最符合需求的模板开始，然后逐步自定义。经常在代表性代码样本上进行测试。

测试配置

# 预览更改而不修改文件
clang-format --dry-run file.cpp

# 显示建议更改的差异
clang-format file.cpp | diff - file.cpp

# 对文件应用格式化
clang-format -i file.cpp

# 格式化整个项目
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# 在 CI 中检查格式化（违规则失败）
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/ 中相关的分类指南。