Mbed TLS Git Hooks 实战：用 pre-push 钩子在推送前自动拦截代码质量问题

Mbed TLS Git Hooks 实战用 pre-push 钩子在推送前自动拦截代码质量问题【免费下载链接】mbedtlsAn open source, portable, easy to use, readable and flexible TLS library, and reference implementation of the PSA Cryptography API. Releases are on a varying cadence, typically around 3 - 6 months between releases.项目地址: https://gitcode.com/GitHub_Trending/mb/mbedtlsMbed TLS 在tests/git-scripts目录下提供了一套可直接启用的 Git hooks 脚本其核心是pre-push钩子在git push真正上传之前自动运行tests/scripts/all.sh -q -k check_*这一组check_*代码检查组件把生成文件一致性、代码风格、命名规范等问题拦截在推送之前。本文介绍如何正确启用这些钩子、钩子脚本的调用约定以及它背后实际执行了哪些检查帮助开发者在本地推送阶段就完成 CI 级别的静态检查。Git hooks 的工作原理与 Mbed TLS 的放置方式Git 提供了一组由特定 git 命令触发的钩子脚本hooks机制官方文档见 git 的 githooks 手册。所有生效的钩子脚本都位于.git/hooks目录中因此钩子本身不在版本控制之下——直接克隆仓库的人不会自动获得这些钩子。Mbed TLS 的做法是把钩子脚本的“源文件”放在仓库内受版本控制的位置再通过软链接接入.git/hooks钩子脚本存放于 tests/git-scripts 目录该目录含 README 与 pre-push.sh需要在Mbed TLS 根目录/.git/hooks下建立指向tests/git-scripts中脚本的软链接钩子才能生效。CONTRIBUTING.md 中也有对应建议在推送更改之前启用 git hooks 脚本可以尽早捕获一些问题。启用步骤Linux/GNU 平台在 Mbed TLS 仓库根目录下的.git/hooks目录中执行ln -s ../../tests/git-scripts/pre-push.sh pre-push这个命令在.git/hooks/内创建软链接pre-push指向仓库中的 tests/git-scripts/pre-push.sh。路径../../恰好对应.git/hooks/ - .git/ - 仓库根目录两级上跳因此链接指向仓库内受版本控制的文件——钩子更新会随git pull同步。重要限制原文档强调目前 Mbed TLS 的 git hooks 仅在 GNU 平台上工作如果使用非 GNU 平台不要启用这些钩子。README 还指出这些脚本也可以脱离 git 独立使用这一点在下一节由脚本自身的注释印证。pre-push.sh 脚本剖析钩子约定与执行内容阅读 tests/git-scripts/pre-push.sh可以看到它严格遵守 Git 对 pre-push 钩子的调用约定调用时机由git push在检查远端状态之后、真正推送之前调用脚本以非零状态退出时本次 push 会被整体阻止“nothing will be pushed”。命令行参数$1是目标 remote 名称$2是推送目标 URL无命名 remote 时两者相等。脚本开头会echo出REMOTE和URL便于调试REMOTE$1 URL$2 echo REMOTE is $REMOTE echo URL is $URLstdin 输入Git 通过标准输入逐行传入被推送的提交信息格式为local ref local sha1 remote ref remote sha1。当前脚本并未逐条解析这些行而是对整个待推送范围统一执行检查。实际动作核心仅一行set -eu tests/scripts/all.sh -q -k check_*set -eu使任何未检查的错误或非零返回都会立即中断脚本从而阻止推送。注意该命令以相对路径tests/scripts/all.sh调用因此必须在仓库根目录作为工作目录运行这与钩子的默认执行环境一致。由于脚本注释明确写着 “This script can also be used independently, not using git”你完全可以在仓库根目录手动执行sh tests/git-scripts/pre-push.sh origin url或直接用tests/scripts/all.sh -q -k check_*完成同样的检查无需依赖 git 触发。钩子背后执行了什么all.sh 与 check_* 组件tests/scripts/all.sh 是 Mbed TLS 测试体系的用户入口与 CI 入口脚本注释说明它必须从项目根目录调用且会加载 framework 子模块中的核心驱动逻辑FRAMEWORK$PWD/framework source $FRAMEWORK/scripts/all-core.sh main $这意味着启用 pre-push 钩子前framework子模块必须已初始化git submodule update --init子模块定义见仓库根目录的.gitmodulesframework指向 mbedtls-framework 仓库。-k check_*参数表示只运行名称匹配check_*的组件-q表示安静输出。这些组件定义在 tests/scripts/components-basic-checks.sh 等文件中check_*前缀的组件包括组件作用见源码注释check_recursion用framework/scripts/recursion.pl检查library/*.c的递归调用问题check_generated_files校验scripts/make_generated_files.py生成文件的一致性分别用make和cmake -D GEN_FILESON两种方式生成后--check比对并同样检查tf-psa-crypto子树check_committed_generated_files运行 tests/scripts/check_committed_generated_files.py检查已提交的生成文件是否与源一致check_doxy_blocks用check-doxy-blocks.pl检查 Doxygen 标记是否都位于 Doxygen 块内check_files文件完整性检查权限、编码check_changelog用assemble_changelog.py重组 ChangeLog 并与已提交的 ChangeLog 比对check_names校验声明与导出的命名需要构建库check_test_cases检查测试用例描述是否符合规范check_test_dependencies检查测试对 crypto 内部宏的依赖维护一份带理由的例外清单如PSA_WANT_ALG_ECDSA_ANY等check_doxygen_warnings构建文档并检查 Doxygen 警告check_code_style用framework/scripts/code_style.py检查 C 代码风格依赖 uncrustify 0.75.1check_python_files对 Python 脚本做 lintcheck_test_helpers对generate_test_code.py、translate_ciphers.py、tests/scripts/test_config_checks.py 等生成器做单元测试从源码结构看-k check_*精确命中了这些静态检查组件而构建、运行测试套件等更耗时的组件不在其中——这解释了为什么 pre-push 钩子可以在每次推送前快速跑完它做的是“推送前质量门禁”而非完整 CI。适用前提与限制平台限制钩子目前仅在 GNU 平台Linux可用非 GNU 平台不要启用见 tests/git-scripts/README.md 的注意事项。子模块依赖all.sh依赖framework子模块启用前需完成git submodule update --initcheck_generated_files等组件还会涉及tf-psa-crypto子树同样需要子模块就位。运行环境部分组件需要make、cmake、python、uncrustify 0.75.1等工具依赖不满足时对应组件会被跳过或报错请依据脚本输出确认。失败即拦截任一check_*组件非零退出push 会被整体阻止这是特性而非缺陷建议先手动运行tests/scripts/all.sh -q -k check_*定位问题再推送。独立使用不依赖 git 时可直接在仓库根目录执行sh tests/git-scripts/pre-push.sh remote url或直接调用tests/scripts/all.sh -q -k check_*完成等价检查。小结Mbed TLS 的 git hooks 方案很轻量受版本控制的脚本存放在 tests/git-scripts通过一条ln -s软链接接入.git/hooks由pre-push钩子在推送前执行 tests/scripts/all.sh 的check_*检查集把生成文件一致性、代码风格、命名与测试规范等静态检查前移到本地推送环节。启用时只需记住两点GNU 平台限制、以及必须在仓库根目录、子模块已初始化后使用。【免费下载链接】mbedtlsAn open source, portable, easy to use, readable and flexible TLS library, and reference implementation of the PSA Cryptography API. Releases are on a varying cadence, typically around 3 - 6 months between releases.项目地址: https://gitcode.com/GitHub_Trending/mb/mbedtls创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考