企业应用后端【免费下载链接】dolibarrDolibarr ERP CRM is a modern software package to manage your company or foundations activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). its an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.项目地址https://gitcode.com/gh_mirrors/do/dolibarr点击查看免费下载# Dolibarr 开发者的 pre-commit 钩子实战指南从安装配置到 CI 集成Dolibarr 是一个基于 PHP 的开源 ERP/CRM 系统代码库庞大且横跨 PHP、YAML、SQL、Shell、JavaScript 多种语言因此保证每一次git commit的代码质量至关重要。本文以仓库中 pre-commit 说明文档 为主线完整讲解 Dolibarr 如何使用 pre-commit 中每一项钩子的作用、配置要点与底层实现帮助你在一台新机器上快速启用这套质量门禁并理解它如何与 CI 流水线协同。读完后你将掌握pre-commit 工具在 Linux/macOS 上的安装、钩子的两种安装方式pre-commit install与手动复制脚本、钩子触发与跳过的常见技巧、Dolibarr 自定义代码规范的落地方式以及.github/workflows/pre-commit.yml中 CI 侧的执行策略。pre-commit 是什么为什么 Dolibarr 需要它pre-commit是一个用于管理和维护多语言 pre-commit 钩子的框架官方网站为 https://pre-commit.org完整文档见 https://pre-commit.com。所谓 pre-commit 钩子是指与git集成、在执行git commit时自动运行的检查程序只要任一检查失败提交就会被中止直到你修复问题或显式跳过检查。在引入该框架之前Dolibarr 仓库内已经存在一个名为precommit的传统钩子脚本见 dev/setup/git/hooks/pre-commit.legacy。这个旧脚本在每次提交时依次运行三件事phplint用php -l对每个暂存的 PHP 文件做语法检查phpcs以 Dolibarr 自定义代码规范扫描代码风格问题phpcbf当检查失败且AUTOFIX1脚本默认值时自动修复代码风格错误并中止本次提交。pre-commit框架与旧的precommit脚本相比最大的优势是不局限于单一语言、也不局限于 PHP它由 Python 生态驱动通过仓库根目录的pre-commit-config.yaml声明式描述钩子列表可组合使用 PHP、Shell、YAML、SQL、Markdown 等几乎任何语言的检查工具。因此虽然它多用于 Python 项目但适用于绝大多数代码与文档开发场景Dolibarr 也正是借助它把代码规范、翻译完整性、静态分析、秘密扫描等几十项检查统一纳入了提交流程。注意pre-commit与旧版precommit是两个不同的东西。Dolibarr 仓库中保留了旧脚本作为历史参考但 dev/setup/git/README.md 明确建议使用新的 pre-commit 钩子文件配合pre-commit install安装效果更好。在本地 git 项目中安装与启用1. 安装 pre-commit 工具本体pre-commit是 Python 包前提是系统中有 Python 与 pip# 若未安装 Python以 Debian/Ubuntu 系为例 sudo apt install python3 # 若未安装 pip sudo apt install pip # 安装 pre-commit 工具 python3 -m pip install pre-commit在较新的发行版如 Debian 12 / Ubuntu 23.04上pip 默认拒绝向系统环境写入包需要追加--break-system-packagespython3 -m pip install pre-commit --break-system-packagesDolibarr 的 PHP 代码检查依赖 PHP_CodeSniffer即phpcs与phpcbf两个命令同样需要安装sudo apt install php-codesniffermacOSHomebrew安装路径# 安装 pipx管理 Python CLI 工具隔离环境 brew install pipx pipx ensurepath # 安装 pre-commit 工具 pipx install pre-commit # 安装 phpcbf 与 phpcs brew install php-codesniffer2. 把钩子挂到你的本地 git 克隆在你的 Dolibarr 本地克隆目录中执行只需一次pre-commit installpre-commit install会在.git/hooks/pre-commit写入一个由框架生成、指向.pre-commit-config.yaml的启动脚本。Dolibarr 文档特别指出推荐直接复制仓库自带的钩子文件因为该文件可能与pre-commit install生成的版本存在差异cp dev/setup/git/hooks/pre-commit .git/hooks/pre-commit对比 dev/setup/git/hooks/pre-commit 与框架默认生成的文件可以发现Dolibarr 维护的这个版本只做了一处关键改造在exec调用中追加了12把 pre-commit 的全部输出重定向到标准错误通道。这样当你在 IDE如 VSCode、PhpStorm里执行提交时IDE 能正确捕获错误信息并展示给开发者而不是被标准输出吞掉。脚本同时保留了回退逻辑优先调用系统 Python 的-mpre_commit否则回退到pre-commit命令两者都不可用时输出提示并退出。理解 Dolibarr 的 pre-commit 配置Dolibarr 的所有钩子声明都集中在仓库根目录的 .pre-commit-config.yaml它采用 pre-commit 标准的repos结构每个repo指向一个 GitHub 仓库或local本地钩子rev固定到某个发布版本hooks列出具体钩子及其参数、文件过滤规则。顶层的全局 exclude 规则配置第一行定义了一个全局排除正则exclude: (?x)^( htdocs/includes/ckeditor/.*|htdocs/public/includes/ckeditor/.*|htdocs/public/includes/jquery/.*|(\.(?!github/workflows)[^/]*/.*))$它表示第三方引入目录htdocs/includes/、htdocs/public/includes/下的编辑器与 jQuery 等以及仓库根目录下所有隐藏文件/目录除.github/workflows外默认不参与检查。这一设计是为了避免对上游库代码做无意义检查、也避免把隐藏配置文件卷入规范化流程。通用代码卫生检查pre-commit/pre-commit-hooks来自pre-commit/pre-commit-hooksrev v6.0.0的通用钩子负责最基础的仓库卫生钩子 id作用关键配置no-commit-to-branch禁止直接在保护分支上提交--branch develop且匹配\d.0$即官方版本号分支如20.0可通过 SKIP 跳过check-xml校验 XML 文件格式排除htdocs/includes/.*check-yaml校验 YAML 文件格式--unsafe允许解析包含特定标签的文件check-json校验 JSON 文件格式无mixed-line-ending统一行尾为 LF替代dev/tools/fixdosfiles.sh排除 TCPDF 字体文件与 swiftmailer 的 CRLF 文件trailing-whitespace删除行尾空白排除 markdown 类型end-of-file-fixer确保文件以单个换行结尾排除 tinymce 目录check-merge-conflict检测未解决的冲突标记阶段含pre-rebase、pre-commit、pre-merge-commitcheck-executables-have-shebangs有 shebang 的可执行文件必须带 shebang无check-shebang-scripts-are-executable带 shebang 的脚本必须在 git 中标记为可执行排除 postgres2mysql、测试文本文件、debian 打包脚本、modulebuilder 模板等fix-byte-order-marker移除 UTF-8 BOM无check-case-conflict检查是否存在仅大小写不同的同名文件Windows 冲突无这些钩子中相当一部分会直接修改文件如mixed-line-ending、trailing-whitespace、end-of-file-fixer、fix-byte-order-marker与文档钩子可能修改你的代码的描述一致——一旦文件被改动本次提交会被取消需要重新提交一次以纳入修复后的内容。秘密扫描gitleaks来自gitleaks/gitleaksrev v8.30.0的gitleaks钩子用于检测并阻止硬编码秘密如密码、API Key、Token 等被提交进 git 仓库属于典型的 SAST静态应用安全测试工具。它默认在每次提交时扫描暂存内容是保护 Dolibarr 这类开源项目供应链安全的重要一环。GitHub Actions 工作流检查actionlint来自rhysd/actionlintrev v1.7.12的actionlint钩子用于校验.github/workflows/下的 GitHub Actions 定义是否正确语法、表达式、引用等。它被标记为stages: [manual]不会在默认提交阶段运行需要手动触发pre-commit run -a --hook-stagemanual actionlintPHP 代码检查与格式化pre-commit-phpPHP 相关的检查来自mdeweerd/pre-commit-phprev v1.6.8这是 Dolibarr 质量门禁的核心php-cbf对*.php文件运行 PHP Code Beautifier and Fixerphpcbf使用 Dolibarr 自定义规范自动修复代码风格参数为--standarddev/setup/codesniffer/ruleset.xmlphp-cs对非htdocs/includes/的 PHP 文件运行 phpcs 代码风格检查参数--standarddev/setup/codesniffer/ruleset.xml、--reportemacsIDE 友好的输出格式、--severity5只报严重级别 ≥5 的问题、--no-colorsphp-cs-with-cachephp-cs的别名变体标记为stages: [manual]配合--cache.cache/pre-commit/dolibarr-php-cs.cache缓存并扫描全仓库供 CI 使用php-lint对所有 PHP 文件做语法检查php -l排除 symfony var-dumper 测试目录php-stanPHPStan 检查stages: [manual]同样只针对 PHP 文件。其中php-cs与php-cbf使用的ruleset.xml位于 dev/setup/codesniffer/ruleset.xml它定义了名为Dolibarr的完整代码规范要点包括统一使用4 空格 Tab 缩进tab-width4行尾必须是 Unix\nLF禁止 BOMGeneric.Files.ByteOrderMark行长度限制宽松lineLimit800禁止短开标签、禁止null/true/false使用大写、禁止过时的 PHP 函数、禁止错误抑制符告警该告警被降级为 0 不显示要求类注释与函数注释PEAR.Commenting.ClassComment、PEAR.Commenting.FunctionComment但将许多误报率高的子规则降级为 0复杂度阈值放宽到环复杂度 250、绝对 500、嵌套 12/50以适应 Dolibarr 大量历史业务代码通过rule refcodesniffer.Dolibarr.LanguageOfComments/与codesniffer.Dolibarr.CheckIsModEnabledArgument引用位于 dev/setup/codesniffer 目录下的自定义 PHPCS 嗅探器强制注释语言、isModEnabled()参数使用等 Dolibarr 特有约定排除第三方与生成代码目录/htdocs/(custom|includes)/、/htdocs/install/doctemplates/websites、/dev/build/、/documents/、.cache、.git等。静态分析PHPStan 与 Phan默认关闭需手动开启.pre-commit-config.yaml 中声明了两个本地钩子用于在提交前运行 PHP 静态分析php-stan入口为 dev/tools/phpstan/allow_phpstan_in_precommit.shphan入口为 dev/tools/phan/allow_phan_in_precommit.sh。这两个脚本的设计思想完全一致默认跳过、按需开启。脚本首先检查~/.run-phpstan/~/.run-phan标记文件是否存在不存在就直接输出 Skipping 并以 0 退出随后检查~/vendor/bin/phpstan/~/vendor/bin/phan是否安装。也就是说如果你想启用这两项重量级检查需要# 启用 PHPStanlevel 9最高严格级别配合 dev/build/phpstan/bootstrap.php 引导 touch ~/.run-phpstan # 启用 Phan touch ~/.run-phan # 不再需要时删除对应标记文件即可PHPStan 脚本还做了作用域过滤只分析htdocs/与scripts/下的文件因为phpstan.neon.dist只覆盖这两个目录并针对批量文件中全部被excludePaths排除导致报 No files found to analyse的情况做了特殊放行处理避免误阻断提交。翻译完整性检查Dolibarr 特色钩子Dolibarr 是国际化项目语言文件多达数千个仓库htdocs/langs/下约 6070 个.lang文件因此配置中专门为翻译文件设计了多个钩子check-translations默认阶段执行调用 dev/translation/sanity_check_trans_missing_unused.sh检查htdocs/langs/en_US/下英文语言文件中是否存在缺失、未使用或重复的翻译键duplicate-lang-lines/duplicate-lang-keysmanual分别调用 dev/tools/fixduplicatelanglines.sh 与 dev/tools/fixduplicatelangkey.sh找出重复的翻译行/键fix-alt-languagesmanual调用 dev/tools/fixaltlanguages_pre-commit.sh按语言前缀正则匹配所有非英文语言文件并同步修复。本地扩展脚本local.sh配置末尾的local-precommit-script钩子是一个巧妙的扩展点- id: local-precommit-script name: Run local script before commit if it exists language: system entry: bash -c [ ! -x local.sh ] || ./local.sh pass_filenames: false它检查仓库根目录是否存在可执行的local.sh存在则执行。你可以在自己的分支上创建local.sh添加私有检查逻辑例如配置注释中给出的示例遍历git diff HEAD --name-only的改动文件对其运行dev/tools/updatelicense.php更新版权头且不把改动写入版本库。这是不修改仓库公共配置即可定制个人工作流的推荐做法。其他可选工具配置中还以stages: [manual]或注释形式声明了更多可选钩子可按需手动执行prettierpre-commit/mirrors-prettierv3.1.0格式化非 PHP 的常见文件排除 php、shell、js、markdown、yaml、css 等大量类型后剩余的文件yamllintadrienverge/yamllintv1.38.0校验 YAML 风格行宽上限 120codespellcodespell-project/codespellv2.4.2拼写纠错使用 dev/tools/codespell 下的三个词表文件codespell-dict.txt自定义词典、codespell-ignore.txt忽略词、codespell-lines-ignore.txt忽略行并针对htdocs/langs/en_US/提供了带专门豁免词的codespell-lang-en_US别名shellcheckshellcheck-py/shellcheck-pyv0.11.0.1检查 Shell 脚本-W 100设置告警级别sqlfluff-lintsqlfluff/sqlfluff4.2.0检查 SQL 文件语法风格manual排除初始化数据 dump、旧迁移脚本、第三方目录等被注释掉的beautyshShell 美化、perltidy、perlcriticPerl 相关因 virtualmin 场景暂缓可作为参考但当前未启用。日常使用触发、跳过与调试提交时的工作流安装钩子后每次git commit都会自动运行全部默认阶段钩子首次运行时 pre-commit 会把所需工具下载安装到~/.cache/pre-commit文档中亦提到运行产物会落到.cache/pre-commit/repo.../pre_commit_hooks/php-....sh等路径。推荐流程如下cd PROJECT_DIR pre-commit install # 只需要执行一次 # 重复直到成功 git commit -a -m My message # pre-commit 会运行并给出报告 # 查看结果、修复问题后重新提交即重复上一行命令关键行为与文档一致一旦检查发现问题git commit 会被中止让你修复或人工复核部分钩子会修改你的代码phpcbf 格式化 PHP、行尾修复、文件末尾修复等如果代码被改动本次提交会被取消再执行一次git commit即可把修复纳入提交钩子还会告警潜在问题语法错误、拼写错误、代码质量、git 仓库中可执行位设置不当等。三种跳过方式场景方法某次提交完全跳过检查git commit -a -m My message --no-verify仅跳过某个钩子在.git/hooks/pre-commit中导出环境变量export SKIPno-commit-to-branch也可写成SKIPno-commit-to-branch git commit -a -m My message单次生效SKIP 支持逗号分隔多个钩子 id永久跳过某个钩子在~/.bashrc或当前会话中export SKIPno-commit-to-branch注意文档给出的 SKIP 示例针对的是no-commit-to-branch钩子——如果你正在自定义分支名而非develop或x.0版本分支上开发该钩子本就不会触发若确实需要在保护分支上临时提交才用上述方式跳过。输出与颜色控制在.git/hooks/pre-commit文件中设置export PRE_COMMIT_COLORnever可以关闭彩色输出、切换为纯文本便于在 CI 日志或纯文本终端中阅读。手动运行与调试除了依赖 git 提交触发pre-commit 支持手动执行全部或单个钩子这在排查问题时非常有用# 手动运行所有默认钩子-a 表示对全部文件而不是仅暂存文件 pre-commit run -a # 手动运行单个钩子 pre-commit run php-cs -a # 运行 manual 阶段的钩子如 SQL 检查、静态分析、缓存版 PHPCS pre-commit run --hook-stage manual -a sqlfluff-lint pre-commit run --hook-stage manual -a php-cs-with-cache pre-commit run --hook-stage manual actionlintCI 如何复用同一套钩子pre-commit 的价值不仅在于本地拦截也在于与 CI 共享同一份配置保证本地与流水线检查结果一致。Dolibarr 在 .github/workflows/pre-commit.yml 中实现了这一点核心思路CI 先以--show-diff-on-failure --coloralways --all-files运行一遍pre-commit run任何失败都会展示修复后的 diff便于定位随后对改动文件运行pre-commit run php-cs针对 PHP 代码规范最后以--hook-stage manual运行php-cs-with-cache带缓存的全量 PHPCS 检查与sqlfluff-lintSQL 检查把重量级/手动阶段的检查也纳入流水线。这正对应文档结尾的结论本地提交时提前暴露问题后你的提交在 GitHub 的 Continuous IntegrationCI运行中更不容易失败——CI 同样运行 pre-commit 以维护代码质量。常见故障排查TroubleshootingModuleNotFoundError: No module named platformdirspre-commit 的 Python 环境缺少依赖pip3 install platformdirs # 或系统级强制安装 pip3 install platformdirs --break-system-packagesModuleNotFoundError: No module named pkg_resourcespkg_resources属于 setuptools在部分 Python 3.12 环境中不再随解释器提供pip3 install pkg_resources # 或 pip3 install pkg_resources --break-system-packagesERROR: PHP_CodeSniffer requires the tokenizer, xmlwriter and SimpleXML extensions to be enabled. Please enable xmlwriter and SimpleXML.PHP_CodeSniffer 需要 PHP 的 tokenizer、xmlwriter 与 SimpleXML 扩展缺少时安装 PHP 的 xml 相关包sudo apt install php-simplexml若你使用第三方 PPA 或发行版php-simplexml包名可能略有差异以发行版软件源为准。总结Dolibarr 的 pre-commit 体系可以概括为三层防护第一层是通用仓库卫生钩子行尾、空白、BOM、冲突标记、大小写冲突保证任何语言的提交都干净整洁第二层是语言专项检查phpcs/phpcbf Dolibarr 自定义 ruleset、gitleaks 秘密扫描、翻译完整性保证 PHP 代码与国际化资产符合项目规范第三层是可选的高阶静态分析PHPStan level 9、Phan、SQL、ShellCheck、Prettier、yamllint 等多数以manual阶段或标记文件开关形式按需启用在 CI 中再以全量模式兜底。配合local.sh扩展点与--no-verify/SKIP/PRE_COMMIT_COLOR等控制手段你可以在不牺牲灵活性的前提下把提交前质量门禁无缝嵌入 Dolibarr 的日常开发流程。赞分享企业应用后端【免费下载链接】dolibarrDolibarr ERP CRM is a modern software package to manage your company or foundations activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). its an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.项目地址https://gitcode.com/gh_mirrors/do/dolibarr点击查看免费下载相关推荐Dolibarr 仓库 Git 开发规范提交模板与 pre-commit 钩子配置实战Dolibarr 仓库 Git 开发规范提交模板与 pre commit 钩子配置实战 导读 Dolibarr README.md https://link企业应用后端终极pre-commit钩子实战指南从零配置到高效代码检查终极pre commit钩子实战指南从零配置到高效代码检查 pre commit钩子是提升代码质量的关键工具能够在提交代码前自动检查并修复常见问题。本文将带开发工具代码质量Lint版本控制Open Source Car Control (OSCC)完全指南从零开始构建自动驾驶车辆控制系统Open Source Car Control OSCC 完全指南从零开始构建自动驾驶车辆控制系统 Open Source Car Control OSCC上一篇如何在5分钟内快速搭建MQTT.js物联网通信系统完整指南下一篇能源消耗预测模型用Python机器学习构建智能能源管理系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Dolibarr 开发者的 pre-commit 钩子实战指南：从安装配置到 CI 集成
企业应用后端【免费下载链接】dolibarrDolibarr ERP CRM is a modern software package to manage your company or foundations activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). its an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.项目地址https://gitcode.com/gh_mirrors/do/dolibarr点击查看免费下载# Dolibarr 开发者的 pre-commit 钩子实战指南从安装配置到 CI 集成Dolibarr 是一个基于 PHP 的开源 ERP/CRM 系统代码库庞大且横跨 PHP、YAML、SQL、Shell、JavaScript 多种语言因此保证每一次git commit的代码质量至关重要。本文以仓库中 pre-commit 说明文档 为主线完整讲解 Dolibarr 如何使用 pre-commit 中每一项钩子的作用、配置要点与底层实现帮助你在一台新机器上快速启用这套质量门禁并理解它如何与 CI 流水线协同。读完后你将掌握pre-commit 工具在 Linux/macOS 上的安装、钩子的两种安装方式pre-commit install与手动复制脚本、钩子触发与跳过的常见技巧、Dolibarr 自定义代码规范的落地方式以及.github/workflows/pre-commit.yml中 CI 侧的执行策略。pre-commit 是什么为什么 Dolibarr 需要它pre-commit是一个用于管理和维护多语言 pre-commit 钩子的框架官方网站为 https://pre-commit.org完整文档见 https://pre-commit.com。所谓 pre-commit 钩子是指与git集成、在执行git commit时自动运行的检查程序只要任一检查失败提交就会被中止直到你修复问题或显式跳过检查。在引入该框架之前Dolibarr 仓库内已经存在一个名为precommit的传统钩子脚本见 dev/setup/git/hooks/pre-commit.legacy。这个旧脚本在每次提交时依次运行三件事phplint用php -l对每个暂存的 PHP 文件做语法检查phpcs以 Dolibarr 自定义代码规范扫描代码风格问题phpcbf当检查失败且AUTOFIX1脚本默认值时自动修复代码风格错误并中止本次提交。pre-commit框架与旧的precommit脚本相比最大的优势是不局限于单一语言、也不局限于 PHP它由 Python 生态驱动通过仓库根目录的pre-commit-config.yaml声明式描述钩子列表可组合使用 PHP、Shell、YAML、SQL、Markdown 等几乎任何语言的检查工具。因此虽然它多用于 Python 项目但适用于绝大多数代码与文档开发场景Dolibarr 也正是借助它把代码规范、翻译完整性、静态分析、秘密扫描等几十项检查统一纳入了提交流程。注意pre-commit与旧版precommit是两个不同的东西。Dolibarr 仓库中保留了旧脚本作为历史参考但 dev/setup/git/README.md 明确建议使用新的 pre-commit 钩子文件配合pre-commit install安装效果更好。在本地 git 项目中安装与启用1. 安装 pre-commit 工具本体pre-commit是 Python 包前提是系统中有 Python 与 pip# 若未安装 Python以 Debian/Ubuntu 系为例 sudo apt install python3 # 若未安装 pip sudo apt install pip # 安装 pre-commit 工具 python3 -m pip install pre-commit在较新的发行版如 Debian 12 / Ubuntu 23.04上pip 默认拒绝向系统环境写入包需要追加--break-system-packagespython3 -m pip install pre-commit --break-system-packagesDolibarr 的 PHP 代码检查依赖 PHP_CodeSniffer即phpcs与phpcbf两个命令同样需要安装sudo apt install php-codesniffermacOSHomebrew安装路径# 安装 pipx管理 Python CLI 工具隔离环境 brew install pipx pipx ensurepath # 安装 pre-commit 工具 pipx install pre-commit # 安装 phpcbf 与 phpcs brew install php-codesniffer2. 把钩子挂到你的本地 git 克隆在你的 Dolibarr 本地克隆目录中执行只需一次pre-commit installpre-commit install会在.git/hooks/pre-commit写入一个由框架生成、指向.pre-commit-config.yaml的启动脚本。Dolibarr 文档特别指出推荐直接复制仓库自带的钩子文件因为该文件可能与pre-commit install生成的版本存在差异cp dev/setup/git/hooks/pre-commit .git/hooks/pre-commit对比 dev/setup/git/hooks/pre-commit 与框架默认生成的文件可以发现Dolibarr 维护的这个版本只做了一处关键改造在exec调用中追加了12把 pre-commit 的全部输出重定向到标准错误通道。这样当你在 IDE如 VSCode、PhpStorm里执行提交时IDE 能正确捕获错误信息并展示给开发者而不是被标准输出吞掉。脚本同时保留了回退逻辑优先调用系统 Python 的-mpre_commit否则回退到pre-commit命令两者都不可用时输出提示并退出。理解 Dolibarr 的 pre-commit 配置Dolibarr 的所有钩子声明都集中在仓库根目录的 .pre-commit-config.yaml它采用 pre-commit 标准的repos结构每个repo指向一个 GitHub 仓库或local本地钩子rev固定到某个发布版本hooks列出具体钩子及其参数、文件过滤规则。顶层的全局 exclude 规则配置第一行定义了一个全局排除正则exclude: (?x)^( htdocs/includes/ckeditor/.*|htdocs/public/includes/ckeditor/.*|htdocs/public/includes/jquery/.*|(\.(?!github/workflows)[^/]*/.*))$它表示第三方引入目录htdocs/includes/、htdocs/public/includes/下的编辑器与 jQuery 等以及仓库根目录下所有隐藏文件/目录除.github/workflows外默认不参与检查。这一设计是为了避免对上游库代码做无意义检查、也避免把隐藏配置文件卷入规范化流程。通用代码卫生检查pre-commit/pre-commit-hooks来自pre-commit/pre-commit-hooksrev v6.0.0的通用钩子负责最基础的仓库卫生钩子 id作用关键配置no-commit-to-branch禁止直接在保护分支上提交--branch develop且匹配\d.0$即官方版本号分支如20.0可通过 SKIP 跳过check-xml校验 XML 文件格式排除htdocs/includes/.*check-yaml校验 YAML 文件格式--unsafe允许解析包含特定标签的文件check-json校验 JSON 文件格式无mixed-line-ending统一行尾为 LF替代dev/tools/fixdosfiles.sh排除 TCPDF 字体文件与 swiftmailer 的 CRLF 文件trailing-whitespace删除行尾空白排除 markdown 类型end-of-file-fixer确保文件以单个换行结尾排除 tinymce 目录check-merge-conflict检测未解决的冲突标记阶段含pre-rebase、pre-commit、pre-merge-commitcheck-executables-have-shebangs有 shebang 的可执行文件必须带 shebang无check-shebang-scripts-are-executable带 shebang 的脚本必须在 git 中标记为可执行排除 postgres2mysql、测试文本文件、debian 打包脚本、modulebuilder 模板等fix-byte-order-marker移除 UTF-8 BOM无check-case-conflict检查是否存在仅大小写不同的同名文件Windows 冲突无这些钩子中相当一部分会直接修改文件如mixed-line-ending、trailing-whitespace、end-of-file-fixer、fix-byte-order-marker与文档钩子可能修改你的代码的描述一致——一旦文件被改动本次提交会被取消需要重新提交一次以纳入修复后的内容。秘密扫描gitleaks来自gitleaks/gitleaksrev v8.30.0的gitleaks钩子用于检测并阻止硬编码秘密如密码、API Key、Token 等被提交进 git 仓库属于典型的 SAST静态应用安全测试工具。它默认在每次提交时扫描暂存内容是保护 Dolibarr 这类开源项目供应链安全的重要一环。GitHub Actions 工作流检查actionlint来自rhysd/actionlintrev v1.7.12的actionlint钩子用于校验.github/workflows/下的 GitHub Actions 定义是否正确语法、表达式、引用等。它被标记为stages: [manual]不会在默认提交阶段运行需要手动触发pre-commit run -a --hook-stagemanual actionlintPHP 代码检查与格式化pre-commit-phpPHP 相关的检查来自mdeweerd/pre-commit-phprev v1.6.8这是 Dolibarr 质量门禁的核心php-cbf对*.php文件运行 PHP Code Beautifier and Fixerphpcbf使用 Dolibarr 自定义规范自动修复代码风格参数为--standarddev/setup/codesniffer/ruleset.xmlphp-cs对非htdocs/includes/的 PHP 文件运行 phpcs 代码风格检查参数--standarddev/setup/codesniffer/ruleset.xml、--reportemacsIDE 友好的输出格式、--severity5只报严重级别 ≥5 的问题、--no-colorsphp-cs-with-cachephp-cs的别名变体标记为stages: [manual]配合--cache.cache/pre-commit/dolibarr-php-cs.cache缓存并扫描全仓库供 CI 使用php-lint对所有 PHP 文件做语法检查php -l排除 symfony var-dumper 测试目录php-stanPHPStan 检查stages: [manual]同样只针对 PHP 文件。其中php-cs与php-cbf使用的ruleset.xml位于 dev/setup/codesniffer/ruleset.xml它定义了名为Dolibarr的完整代码规范要点包括统一使用4 空格 Tab 缩进tab-width4行尾必须是 Unix\nLF禁止 BOMGeneric.Files.ByteOrderMark行长度限制宽松lineLimit800禁止短开标签、禁止null/true/false使用大写、禁止过时的 PHP 函数、禁止错误抑制符告警该告警被降级为 0 不显示要求类注释与函数注释PEAR.Commenting.ClassComment、PEAR.Commenting.FunctionComment但将许多误报率高的子规则降级为 0复杂度阈值放宽到环复杂度 250、绝对 500、嵌套 12/50以适应 Dolibarr 大量历史业务代码通过rule refcodesniffer.Dolibarr.LanguageOfComments/与codesniffer.Dolibarr.CheckIsModEnabledArgument引用位于 dev/setup/codesniffer 目录下的自定义 PHPCS 嗅探器强制注释语言、isModEnabled()参数使用等 Dolibarr 特有约定排除第三方与生成代码目录/htdocs/(custom|includes)/、/htdocs/install/doctemplates/websites、/dev/build/、/documents/、.cache、.git等。静态分析PHPStan 与 Phan默认关闭需手动开启.pre-commit-config.yaml 中声明了两个本地钩子用于在提交前运行 PHP 静态分析php-stan入口为 dev/tools/phpstan/allow_phpstan_in_precommit.shphan入口为 dev/tools/phan/allow_phan_in_precommit.sh。这两个脚本的设计思想完全一致默认跳过、按需开启。脚本首先检查~/.run-phpstan/~/.run-phan标记文件是否存在不存在就直接输出 Skipping 并以 0 退出随后检查~/vendor/bin/phpstan/~/vendor/bin/phan是否安装。也就是说如果你想启用这两项重量级检查需要# 启用 PHPStanlevel 9最高严格级别配合 dev/build/phpstan/bootstrap.php 引导 touch ~/.run-phpstan # 启用 Phan touch ~/.run-phan # 不再需要时删除对应标记文件即可PHPStan 脚本还做了作用域过滤只分析htdocs/与scripts/下的文件因为phpstan.neon.dist只覆盖这两个目录并针对批量文件中全部被excludePaths排除导致报 No files found to analyse的情况做了特殊放行处理避免误阻断提交。翻译完整性检查Dolibarr 特色钩子Dolibarr 是国际化项目语言文件多达数千个仓库htdocs/langs/下约 6070 个.lang文件因此配置中专门为翻译文件设计了多个钩子check-translations默认阶段执行调用 dev/translation/sanity_check_trans_missing_unused.sh检查htdocs/langs/en_US/下英文语言文件中是否存在缺失、未使用或重复的翻译键duplicate-lang-lines/duplicate-lang-keysmanual分别调用 dev/tools/fixduplicatelanglines.sh 与 dev/tools/fixduplicatelangkey.sh找出重复的翻译行/键fix-alt-languagesmanual调用 dev/tools/fixaltlanguages_pre-commit.sh按语言前缀正则匹配所有非英文语言文件并同步修复。本地扩展脚本local.sh配置末尾的local-precommit-script钩子是一个巧妙的扩展点- id: local-precommit-script name: Run local script before commit if it exists language: system entry: bash -c [ ! -x local.sh ] || ./local.sh pass_filenames: false它检查仓库根目录是否存在可执行的local.sh存在则执行。你可以在自己的分支上创建local.sh添加私有检查逻辑例如配置注释中给出的示例遍历git diff HEAD --name-only的改动文件对其运行dev/tools/updatelicense.php更新版权头且不把改动写入版本库。这是不修改仓库公共配置即可定制个人工作流的推荐做法。其他可选工具配置中还以stages: [manual]或注释形式声明了更多可选钩子可按需手动执行prettierpre-commit/mirrors-prettierv3.1.0格式化非 PHP 的常见文件排除 php、shell、js、markdown、yaml、css 等大量类型后剩余的文件yamllintadrienverge/yamllintv1.38.0校验 YAML 风格行宽上限 120codespellcodespell-project/codespellv2.4.2拼写纠错使用 dev/tools/codespell 下的三个词表文件codespell-dict.txt自定义词典、codespell-ignore.txt忽略词、codespell-lines-ignore.txt忽略行并针对htdocs/langs/en_US/提供了带专门豁免词的codespell-lang-en_US别名shellcheckshellcheck-py/shellcheck-pyv0.11.0.1检查 Shell 脚本-W 100设置告警级别sqlfluff-lintsqlfluff/sqlfluff4.2.0检查 SQL 文件语法风格manual排除初始化数据 dump、旧迁移脚本、第三方目录等被注释掉的beautyshShell 美化、perltidy、perlcriticPerl 相关因 virtualmin 场景暂缓可作为参考但当前未启用。日常使用触发、跳过与调试提交时的工作流安装钩子后每次git commit都会自动运行全部默认阶段钩子首次运行时 pre-commit 会把所需工具下载安装到~/.cache/pre-commit文档中亦提到运行产物会落到.cache/pre-commit/repo.../pre_commit_hooks/php-....sh等路径。推荐流程如下cd PROJECT_DIR pre-commit install # 只需要执行一次 # 重复直到成功 git commit -a -m My message # pre-commit 会运行并给出报告 # 查看结果、修复问题后重新提交即重复上一行命令关键行为与文档一致一旦检查发现问题git commit 会被中止让你修复或人工复核部分钩子会修改你的代码phpcbf 格式化 PHP、行尾修复、文件末尾修复等如果代码被改动本次提交会被取消再执行一次git commit即可把修复纳入提交钩子还会告警潜在问题语法错误、拼写错误、代码质量、git 仓库中可执行位设置不当等。三种跳过方式场景方法某次提交完全跳过检查git commit -a -m My message --no-verify仅跳过某个钩子在.git/hooks/pre-commit中导出环境变量export SKIPno-commit-to-branch也可写成SKIPno-commit-to-branch git commit -a -m My message单次生效SKIP 支持逗号分隔多个钩子 id永久跳过某个钩子在~/.bashrc或当前会话中export SKIPno-commit-to-branch注意文档给出的 SKIP 示例针对的是no-commit-to-branch钩子——如果你正在自定义分支名而非develop或x.0版本分支上开发该钩子本就不会触发若确实需要在保护分支上临时提交才用上述方式跳过。输出与颜色控制在.git/hooks/pre-commit文件中设置export PRE_COMMIT_COLORnever可以关闭彩色输出、切换为纯文本便于在 CI 日志或纯文本终端中阅读。手动运行与调试除了依赖 git 提交触发pre-commit 支持手动执行全部或单个钩子这在排查问题时非常有用# 手动运行所有默认钩子-a 表示对全部文件而不是仅暂存文件 pre-commit run -a # 手动运行单个钩子 pre-commit run php-cs -a # 运行 manual 阶段的钩子如 SQL 检查、静态分析、缓存版 PHPCS pre-commit run --hook-stage manual -a sqlfluff-lint pre-commit run --hook-stage manual -a php-cs-with-cache pre-commit run --hook-stage manual actionlintCI 如何复用同一套钩子pre-commit 的价值不仅在于本地拦截也在于与 CI 共享同一份配置保证本地与流水线检查结果一致。Dolibarr 在 .github/workflows/pre-commit.yml 中实现了这一点核心思路CI 先以--show-diff-on-failure --coloralways --all-files运行一遍pre-commit run任何失败都会展示修复后的 diff便于定位随后对改动文件运行pre-commit run php-cs针对 PHP 代码规范最后以--hook-stage manual运行php-cs-with-cache带缓存的全量 PHPCS 检查与sqlfluff-lintSQL 检查把重量级/手动阶段的检查也纳入流水线。这正对应文档结尾的结论本地提交时提前暴露问题后你的提交在 GitHub 的 Continuous IntegrationCI运行中更不容易失败——CI 同样运行 pre-commit 以维护代码质量。常见故障排查TroubleshootingModuleNotFoundError: No module named platformdirspre-commit 的 Python 环境缺少依赖pip3 install platformdirs # 或系统级强制安装 pip3 install platformdirs --break-system-packagesModuleNotFoundError: No module named pkg_resourcespkg_resources属于 setuptools在部分 Python 3.12 环境中不再随解释器提供pip3 install pkg_resources # 或 pip3 install pkg_resources --break-system-packagesERROR: PHP_CodeSniffer requires the tokenizer, xmlwriter and SimpleXML extensions to be enabled. Please enable xmlwriter and SimpleXML.PHP_CodeSniffer 需要 PHP 的 tokenizer、xmlwriter 与 SimpleXML 扩展缺少时安装 PHP 的 xml 相关包sudo apt install php-simplexml若你使用第三方 PPA 或发行版php-simplexml包名可能略有差异以发行版软件源为准。总结Dolibarr 的 pre-commit 体系可以概括为三层防护第一层是通用仓库卫生钩子行尾、空白、BOM、冲突标记、大小写冲突保证任何语言的提交都干净整洁第二层是语言专项检查phpcs/phpcbf Dolibarr 自定义 ruleset、gitleaks 秘密扫描、翻译完整性保证 PHP 代码与国际化资产符合项目规范第三层是可选的高阶静态分析PHPStan level 9、Phan、SQL、ShellCheck、Prettier、yamllint 等多数以manual阶段或标记文件开关形式按需启用在 CI 中再以全量模式兜底。配合local.sh扩展点与--no-verify/SKIP/PRE_COMMIT_COLOR等控制手段你可以在不牺牲灵活性的前提下把提交前质量门禁无缝嵌入 Dolibarr 的日常开发流程。赞分享企业应用后端【免费下载链接】dolibarrDolibarr ERP CRM is a modern software package to manage your company or foundations activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). its an open source Web application (written in PHP) designed for businesses of any sizes, foundations and freelancers.项目地址https://gitcode.com/gh_mirrors/do/dolibarr点击查看免费下载相关推荐Dolibarr 仓库 Git 开发规范提交模板与 pre-commit 钩子配置实战Dolibarr 仓库 Git 开发规范提交模板与 pre commit 钩子配置实战 导读 Dolibarr README.md https://link企业应用后端终极pre-commit钩子实战指南从零配置到高效代码检查终极pre commit钩子实战指南从零配置到高效代码检查 pre commit钩子是提升代码质量的关键工具能够在提交代码前自动检查并修复常见问题。本文将带开发工具代码质量Lint版本控制Open Source Car Control (OSCC)完全指南从零开始构建自动驾驶车辆控制系统Open Source Car Control OSCC 完全指南从零开始构建自动驾驶车辆控制系统 Open Source Car Control OSCC上一篇如何在5分钟内快速搭建MQTT.js物联网通信系统完整指南下一篇能源消耗预测模型用Python机器学习构建智能能源管理系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考