dsh-git-guard

@deepwhale-cn/dsh-git-guard

Git 提交前检查：把「密钥进仓库」「5MB 大文件」「冲突标记」「调试残留」「被跟踪的 .env」「不规范的 commit message」拦在 commit 之前。

关键词：Git 提交前检查 · pre-commit hook · 密钥扫描 · 大文件 · 冲突标记 · 调试残留 · commit message 规范 · git hook · CI 卡口 Keywords: git pre-commit hook · secret scan · commitlint · large file · merge conflict marker · debugger residue

不装会怎样

密钥写进源码、.env 被 git add . 顺手带上、5MB 视频进了仓库、<<<<<<< HEAD 忘了删、console.log 和 debugger 留在生产代码里 —— 这些问题的共同点是：提交那一刻没人拦，事后清理成本极高（密钥要作废轮换、大文件要重写历史、冲突标记直接把线上搞崩）。这个插件就是提交前最后一道闸。

能做什么

• scan：扫工作区 / 暂存区，报告六类问题：
  • 疑似密钥 token（AWS / GitHub / Slack / Stripe / Google / 通用 api_key=...）
  • 私钥文件（-----BEGIN ... PRIVATE KEY-----）
  • 超过 5MB 的大文件（默认阈值，可用 --max-size 调整）
  • 残留合并冲突标记（<<<<<<< / ======= / >>>>>>>）
  • 调试残留（debugger、console.log / console.debug，按警告处理）
  • 被 Git 跟踪的 .env（.env.example / .env.sample 等不算）
• msg：校验 commit message 是否符合 type(scope): subject 约定（type 白名单、标题 ≤72 字、标题与正文之间空一行、subject 不以句号结尾等；Merge / Revert / fixup! 自动豁免）。
• precommit：组合 staged 扫描 + message 校验，有问题退出 1，可直接挂 git hook；precommit install 一键写入 .git/hooks/pre-commit（原 hook 自动备份为 .bak）。
• 两种输出：终端里给人看的分组报告；--json 给 CI；--out 额外写一份 Markdown 报告。
• --demo：自造一个临时 Git 仓库（密钥均为伪造值），把六类问题 + message 校验整套跑一遍，打印产物路径。

不能做什么

• ❌ 不扫历史提交：只检查当前工作区 / 暂存区，已经提交过的密钥请另行轮换并用 git filter-repo 等工具处理历史。
• ❌ 不是完整秘密扫描器：没做熵值检测、不覆盖所有厂商的 token 格式；正则命中是提示，需要人确认，不是「安全/不安全」判定。
• ❌ 不管理 hook：只写 .git/hooks/pre-commit（会备份原文件），不接管 husky / lefthook 等工具；团队流水线请按自己的编排接入。
• ❌ message 规则是常见子集：Conventional Commits 的常见 type 集合，团队自定义 type / 模板需自行扩展代码。
• ❌ console.log 只算警告：默认不拦截（--strict 可把警告也当错误）；也不分辨日志是否在测试文件里。
• ❌ 不自动迁移大文件：只报出来，不会执行 Git LFS 或重写历史。
• ⚠️ 需要本机装 Git；纯 Node ESM，不联网、不装依赖。
• ⚠️ 挂 pre-commit 的前提：当前目录是已 git init 的仓库（hook 写入 .git/hooks/）；在非 git 目录装插件不会自动生效，先 git init 或按 precommit install 提示操作。

安装

dsh plugin --profile web add @deepwhale-cn/dsh-git-guard
# 或纯 CLI
npx @deepwhale-cn/dsh-git-guard --help

用法

dsh-git-guard scan                        # 扫当前仓库（工作区 + 暂存区）
dsh-git-guard scan staged --input <目录>  # 只看暂存区
dsh-git-guard scan --json                 # 给 CI
dsh-git-guard msg --message "feat(api): 支持批量导出"
dsh-git-guard precommit --input <目录>    # 退出码 1 = 拦下提交
dsh-git-guard precommit install --input <目录>
dsh-git-guard --demo

挂进 git hook 后，每次 git commit 前自动跑 precommit；退出码 1 会阻止提交。 确实需要跳过时用 git commit --no-verify（不建议）。

License

MIT © 温州深鲸智能科技有限公司