企业官网建设流程全解析

CANN shmem 仓库 Pre-commit 代码质量检查使用指南：从安装配置到源码级规则解析

【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库，基于OpenSHMEM 标准协议，实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem

导读

本文基于 CANN shmem 开源仓库的 pre-commit 使用指南，系统讲解如何在昇腾内存通信库的日常开发中，用 pre-commit 框架在git commit前自动完成 Python 与 C/C++ 代码的格式化、Lint、安全与拼写检查。读完本文，你将掌握 hook 的安装与触发方式、手动/自动检查的完整命令、仓库内 6 类检查工具（ruff、pylint、bandit、codespell、typos、clang-format）的职责与配置文件，并结合.pre-commit-config.yaml、pyproject.toml、.clang-format、typos.toml 等真实配置，理解每条规则背后的实现意图与调试方法。

一、为什么在提交前做自动检查

CANN shmem 是一个横跨 C/C++ 设备侧内核（src/device、src/device_simt）、主机侧实现（src/host）、Python 扩展与测试脚本（src/python、tests、examples）的大型混合语言仓库。多语言、多贡献者协作时，最容易出现的问题是：代码风格不一致、低级语法错误、拼写错误混入提交、甚至敏感信息或超大文件被误提交。

本项目选择 pre-commit，minimum_pre_commit_version要求为4.0.0，并约定default_stages: [pre-commit]（即在 pre-commit 阶段触发），同时排除LICENSES/目录与.html/.csv/.svg文件。

二、安装与初始化

1. 安装 pre-commit 框架

pip install pre-commit

建议使用与仓库一致的 Python 环境（仓库根目录提供 requirements.txt 与 setup.py，版本管理统一的环境可避免 hook 运行时依赖冲突）。

2. 安装 Git Hooks（推荐）

pre-commit install

该命令会把 hook 写入本地.git/hooks/pre-commit。安装后，每次执行git commit都会自动触发配置中声明的全部检查。若首次提交前想验证整体流程，可先运行：

pre-commit run --all-files

这会在不提交任何内容的前提下，把全仓库文件完整检查一遍，是最稳妥的"冒烟测试"方式。

三、日常使用：自动检查与手动检查

自动检查（推荐）

git add . git commit -m "your message"

提交时 pre-commit 会仅对暂存区（staged）中的文件执行检查。如果检查失败，部分工具会自动修复——例如仓库配置中 clang-format 使用了-i参数（原地改写文件），ruff-format 会直接重排 Python 代码——修复后文件内容已变化，需重新git add再提交：

git add . git commit -m "your message"

手动检查

检查当前暂存的所有文件：

pre-commit run

只检查指定文件（可指定任意路径，无需暂存）：

pre-commit run ruff-check --files path/to/file.py pre-commit run clang-format --files path/to/file.cpp

只运行单个 hook：

pre-commit run ruff-check pre-commit run pylint pre-commit run clang-format pre-commit run codespell pre-commit run typos

运行全部 hook 并显示更详细的输出：

pre-commit run --verbose --all-files

跳过检查（不推荐）

git commit --no-verify -m "your message"

--no-verify会绕过所有 Git Hook。仓库文档明确提示：频繁跳过检查可能让问题代码进入仓库，仅建议在极端情况下（如临时修复 CI 阻断、纯文档紧急修改）使用，事后应尽快补跑检查。

四、检查工具总览

仓库通过 .pre-commit-config.yaml 聚合了以下工具，覆盖 Python、C/C++ 与通用文本三类检查：

此外，tools/pre-commit/check_header_inclusion.py 是仓库自带的自定义检查脚本（详见第六节）。

五、配置文件逐一解读

1. 主配置文件.pre-commit-config.yaml

位于仓库根目录，声明了全部 repo 与 hook 列表。逐一拆解：

基础检查（pre-commit-hooks，v4.6.0）：

C++ 格式化（mirrors-clang-format，v18.1.8）：

- id: clang-format files: \.(c|h|cpp|hpp|cc|hh|cxx|hxx|asc)$ args: ["--style=file", "--verbose", "-i"] exclude: ^build/|tests/third_party/

要点：--style=file表示读取根目录 .clang-format 的规则；-i允许自动原地修复；文件范围覆盖.c/.h/.cpp/.hpp/.cc/.hh/.cxx/.hxx/.asc（.asc为昇腾 AscendC 内核源文件扩展名，契合本仓库设备侧开发场景）；构建产物目录与tests/third_party/被排除。

拼写检查（codespell，v2.4.1）：

- id: codespell args: ["-L", "CANN,cann,NNAL,nnal,ASCEND,ascend,EnQue,CopyIn,ArchType,AND,ND,tbe,copyin,alog,CLOS,iput,iget,VAs", "--skip", "*.py,*.cpp,*.hpp,*.c,*.h,tools/pre-commit/typos.toml"]

-L声明忽略词列表，其中iput/iget是 OpenSHMEM 步长（strided）RMA 接口的合法术语而非 "input" 的拼写错误，CANN/ASCEND等是平台品牌名，EnQue/CopyIn/ArchType等是昇腾内核编程常见标识符；--skip排除了会干扰拼写检查的源码与白名单文件。

2. Python 工具配置tools/pre-commit/pyproject.toml

该文件同时承载 ruff、pylint、bandit 三段配置，设计理念是"高价值规则全开、洁癖规则全关"：

• ruff：line-length = 120，目标版本py310；在保持默认规则集基础上通过extend-select追加D209（多行 docstring 的收尾"""必须独占一行）与SIM115（推荐用with代替 try-finally 管理资源）。
• pylint：reports = false、score = false、max-line-length = 120；只enable真正会导致崩溃的 BUG 级规则，例如E0100（语法错误）、E0601（使用未定义变量）、E0611（导入不存在的包）、E1101（访问不存在成员）、W0632（元组解包不匹配）与W1514（open 未指定 encoding 导致跨平台乱码）；同时disable所有命名、docstring、复杂度、未使用变量等风格类警告。
• bandit：severity_level与confidence_level均为MEDIUM，即中高危漏洞全部上报；exclude_dirs跳过tests、venv、build、migrations、tools/pre-commit等目录；skips = []表示启用全部安全检查，输出为screen格式且quiet = true。

3. C++ 格式化规则.clang-format

基于 Google 风格定制，核心参数如下：

• ColumnLimit: 120（与 Python 侧 120 列保持一致）；
• IndentWidth: 4、TabWidth: 4、UseTab: Never——统一 4 空格缩进、禁用 Tab；
• PointerAlignment: Left——指针星号靠左，如char* p；
• SortIncludes: false——不强制重排 include 顺序，尊重开发者手写的头文件排列；
• BreakBeforeBraces: Custom配合BraceWrapping.AfterFunction: true——函数左大括号换行，而类、结构体、命名空间、enum 采用紧凑风格同行放置；
• AlignAfterOpenBracket: AlwaysBreak、AlignTrailingComments: true——括号内多行参数自动换行对齐、行尾注释右对齐；
• AllowShortFunctionsOnASingleLine: true而AllowShortBlocksOnASingleLine: false——短函数可单行，但控制语句块不允许单行压缩。

4. 拼写检查白名单tools/pre-commit/typos.toml

typos 在扫描仓库文本时可能对昇腾生态特有的标识符与专有名词误报，因此该文件按文件类型（type.py、type.cpp、type.sh、type.jl、type.go等）分别维护白名单：

• extend-ignore-words-re忽略CANN、ND、alog、CLOS等专有词；
• extend-ignore-identifiers-re忽略.*Unc.*、.*UE8M0.*、.*[UE4M3|ue4m3].*等昇腾数据类型；
• [default.extend-identifiers]逐个登记合法标识符，如subtile、SFOuput、NDArray、arange等；
• [default.extend-words]登记合法单词，如dout、Pn、arange、iy；
• ignore-files = true、ignore-hidden = true、locale = "en"等为扫描行为基线，check-filename = false表示不检查文件名本身。

六、仓库自研检查脚本：头文件显式包含检查

除第三方工具外，仓库在 tools/pre-commit/check_header_inclusion.py 提供了一个基于 clang-tidymisc-include-cleaner的 AST 级头文件包含检查脚本，弥补通用工具无法感知项目内部 include 卫生的不足。其设计要点：

• 三类检查：标准库头文件必须显式包含（缺失则提示补充对应头文件）；.h/.hpp头文件必须自包含（自用类型/宏的来源头文件必须被 include）；未直接使用的 include 会被报告为冗余。
• 免构建的 include 路径自动发现：脚本会递归扫描include、src、examples三个根目录寻找含头文件的目录（第 46-61 行）；若存在build/compile_commands.json则从中提取-I/-D/-std=编译参数（第 140-197 行）。
• 昇腾工具链适配：自动探测ASCEND_HOME_PATH、ASCEND_TOOLKIT_HOME环境变量及/usr/local/Ascend/ascend-toolkit/latest等常见路径下的kernel_operator.h、kernel_tpipe.h等 AscendC 头文件目录（第 64-123 行）。
• 容错机制：当 clang-tidy 因工具链头文件缺失无法解析源码时，脚本输出SKIP而非误报失败（第 360-379 行）；支持--check stdlib|header_self|unused|all、--output text|json等参数（第 386-413 行）。

脚本由python tools/pre-commit/check_header_inclusion.py [files ...]调用，可配合 pre-commit 的additional_dependencies挂入任意仓库。仓库根目录的 pre-commit 主配置中虽未默认启用该脚本，但其逻辑与 clang-format 形成了"C/C++ 格式 + 头文件卫生"的互补检查链。

七、常见问题排查

Q1：检查失败怎么办？

先区分两类失败：自动可修复——ruff-format、clang-format 等带-i/format 能力的 hook 会直接改写文件，重新git add后提交即可；需手动修复——pylint、bandit、codespell、typos 等只报告不修改，按输出中的文件路径与行号定位修改后重新提交。

Q2：如何更新 hooks 到最新版本？

pre-commit autoupdate

注意两点：其一，主配置中ci.autoupdate_schedule: monthly表明 CI 侧每月自动更新一次，本地可主动同步；其二，更新可能带来新规则导致旧代码突然不通过，建议在独立提交中升级 hooks 并一并修复增量问题。仓库已为各工具锁定 rev（如 clang-format v18.1.8、codespell v2.4.1、pre-commit-hooks v4.6.0），升级前可对比当前锁定版本。

Q3：如何查看某个工具的详细错误信息？

pre-commit run pylint --verbose

--verbose会输出 hook 的执行环境、传入参数与完整 stderr；对自定义脚本（如 check_header_inclusion.py）还可直接手动执行并附加--output json获取结构化结果。若需要一次性查看全仓库所有文件的全部报告，可组合--all-files --verbose。

Q4：如何临时禁用某条规则？

Python（ruff/pylint）：在代码行尾添加行内禁用注释：

x = 1 # pylint: disable=invalid-name

C++（clang-format）：用注释包围需要豁免的代码段：

// clang-format off int unformatted_code = 1; // clang-format on

拼写检查（codespell/typos）：优先把合法术语加入 typos.toml 的白名单（见第五节），避免用全局--no-verify掩盖问题。需要特别提醒：禁用规则属于例外而非常态，行内豁免只应针对确有必要保持原样的代码（如生成代码、跨平台兼容写法）。

Q5：首次运行很慢怎么办？

首次运行需要按 .pre-commit-config.yaml 中声明的repo地址下载并安装每个工具到独立虚拟环境（如 pip 安装的 clang-tidy 位于项目.venv/bin/clang-tidy），之后全部运行都会命中 pre-commit 缓存，速度显著提升。若仓库长期未跑检查，可先用pre-commit run --all-files预热环境并集中修复存量问题，再进入日常增量检查节奏。

八、最佳实践

1. 安装 Git Hooks：pre-commit install让每次提交自动检查，避免"先提交、后 CI 报错"的返工循环。
2. 不要频繁使用--no-verify：跳过检查会让未格式化代码、拼写错误甚至安全问题流入主干，破坏仓库的基线质量。
3. 及时更新 hooks：定期运行pre-commit autoupdate获取工具新版本；升级后先在独立分支验证全部检查通过再合入。
4. 配置 IDE 集成：在 IDE 中安装 ruff、clang-format 插件实现实时提示，把检查从"提交时拦截"前移到"编码时纠正"，配合本仓库的 coding_style_guide.md 可快速形成统一编码习惯。
5. 善用增量检查：日常开发使用pre-commit run --files <file>只查改动文件，既快又精准；合入前再跑一次--all-files兜底。
6. 理解规则意图：本仓库的 pylint 配置刻意关闭风格类检查、只保留崩溃级规则，意味着高价值问题优先、噪声最小化是团队的工程取舍；遇到 hook 报错时，先判断它属于 BUG 级问题、安全风险、拼写误报还是格式问题，再决定修复或登记白名单。

结语

pre-commit 在 CANN shmem 仓库中扮演着"提交前质量闸门"的角色：ruff/pylint/bandit 守住 Python 侧的质量与安全底线，clang-format 统一 C/C++ 与 AscendC 内核代码风格，codespell/typos 过滤拼写噪声，基础 hooks 拦截私钥、大文件、合并冲突等低级事故。理解 .pre-commit-config.yaml 及其配套配置文件，你不仅能顺畅通过本仓库的提交检查，也能把这套"多语言、规则克制、可自动修复优先"的实践复用到自己的项目中去。

【免费下载链接】shmemCANN SHMEM 是面向昇腾平台的多机多卡内存通信库，基于OpenSHMEM 标准协议，实现跨设备的高效内存访问与数据同步。项目地址: https://gitcode.com/cann/shmem