正确姿势是在.git/hooks/pre-commit中编写shell脚本，仅扫描git diff --cached筛选出的暂存区java文件，先cd到仓库根目录，调用checkstyle -c checkstyle.xml或mvn checkstyle:check -q，并严格依据退出码中断提交，同时添加--fail-on-violation和-q参数确保行为一致、输出简洁。
Git Hook 里调用 Checkstyle 的正确姿势
Checkstyle 本身不提供 Git Hook 集成能力，必须靠 shell 脚本桥接。关键不是“能不能跑”，而是“只检查即将提交的文件”，否则每次提交都扫全量代码，既慢又误报。
推荐在 .git/hooks/pre-commit 中写 shell 脚本，用 git diff --cached --name-only --diff-filter=ACM 提取本次新增/修改/重命名的 Java 文件，再喂给 Checkstyle 扫描。
- 别直接执行
checkstyle -c checkstyle.xml src/—— 这会扫整个源码树，CI 里可以，pre-commit 里不行 - 确保脚本开头加
#!/bin/sh，避免 macOS/Linux 解释器差异导致 hook 失效 - Checkstyle CLI 必须已安装且在
$PATH中；若用 Maven 管理，改用mvn checkstyle:check -q更稳妥（但需提前配置好maven-checkstyle-plugin）
pre-commit 脚本如何判断 Checkstyle 是否失败
Checkstyle CLI 默认成功时退出码为 0，有违规时退出码为 1（注意：不是所有版本都一致，checkstyle-10.12.0 及之后才统一）。但 pre-commit 脚本必须严格依赖退出码中断提交，否则“警告当过”的问题就来了。
- 用
set -e或显式检查$?，例如：if [ $? -ne 0 ]; then echo "Checkstyle failed"; exit 1; fi - 别忽略
-q（quiet）参数：不加的话，Checkstyle 会在 stdout 输出大量违规详情，干扰 Git 的提交提示，甚至导致某些 IDE 的 Git UI 解析异常 - 如果团队允许部分豁免（比如生成代码），要在
checkstyle.xml里用<suppress-checks></suppress-checks>配置，而不是在脚本里绕过文件过滤
Java 文件路径传给 Checkstyle 时的常见坑
Git 返回的是相对路径（如 src/main/java/com/example/Service.java），而 Checkstyle 默认以当前目录为基准解析。一旦你在子模块或非项目根目录执行 git commit，路径就会错位，导致 “file not found” 错误。
- 脚本中先
cd $(git rev-parse --show-toplevel)切到仓库根，再运行 Checkstyle - 不要拼接绝对路径，避免 CI 和本地环境行为不一致
- 遇到 Windows 用户，注意 Git Bash 下路径分隔符是
/，但 Checkstyle 在 Windows 上可能期望\—— 统一用git ls-files+xargs或while read循环处理更可靠
为什么建议用 Husky + lint-staged 替代原生 Git Hook
原生 .git/hooks 不随 git clone 自动同步，每个开发者都要手动复制脚本，协作成本高。Husky 能把钩子声明写进 package.json，配合 lint-staged 实现“仅对暂存区 Java 文件执行 Checkstyle”，语义更清晰、维护更集中。
- 安装后，在
package.json中配："husky": {"hooks": {"pre-commit": "lint-staged"}}，再配"lint-staged": {"*.java": ["checkstyle -c checkstyle.xml --fail-on-violation"]} - 注意
--fail-on-violation参数：它强制 Checkstyle 在发现任何违规时返回非零退出码，没有这个，pre-commit 就不会中断 - 如果项目没用 npm，就老实用原生 hook；别为了用 Husky 引入 Node.js 依赖，得不偿失
真正难的不是让 Checkstyle 跑起来，而是让所有人每次提交时都面对同一套规则、同一份配置、同一个退出逻辑。路径处理错一次，或者忘了 --fail-on-violation，整套机制就形同虚设。
