claude-howto 中 /push-all 命令详解：带安全检查与确认门禁的 Git 提交推送 Slash Command 模板

本文以 claude-howto 仓库中的 push-all.md 为核心素材，完整拆解 /push-all 这条 Claude Code Slash Command 模板的设计思想与七步工作流：分析变更、安全检查、人工确认、暂存提交、生成 Conventional Commit 信息、推送远程以及成功确认。读完后你可以直接将该模板安装为自己的自定义命令，并理解它如何通过 allowed-tools 白名单、密钥检测规则和显式确认门禁，让"一键提交推送"这种高危操作变得可控。

/push-all 是什么

/push-all 是一个封装"Stage all changes, create commit, and push to remote"的自定义 Slash Command，其文件元信息（frontmatter）完整定义了它的行为边界：

---
description: Stage all changes, create commit, and push to remote (use with caution)
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*)
---

模板开头就带有一条醒目的警告：

⚠️ CAUTION: Stage ALL changes, commit, and push to remote. Use only when confident all changes belong together.

从设计上看，这条命令有三个关键决策：

1. allowed-tools 最小权限白名单：只放行 git add / status / commit / push / diff / log / pull 七个只读或提交类的 git 子命令模式，其余 Bash 调用（如 rm、curl、任意脚本）都需要额外授权。这是把"能做什么"收敛到"只该做什么"的第一道防线。
2. 显式确认门禁（Confirmation Gate）：模板要求 Claude 在执行 git add . 之前，必须先向用户展示变更摘要并等待输入 yes 才能继续。命令的"自动化"止步于确认点，人保留最终决定权。
3. 推送前安全检查：把密钥泄露、大文件、构建产物、临时文件等典型"误提交"场景全部列成检查清单，要求逐条过筛后才允许进入暂存阶段。

该模板在 01-slash-commands/README.md 的目录索引中归类为 "Quick push workflow"，与 /commit、/pr 共同构成仓库的 Git 工作流命令族；模板页脚标注其写作基线为 Claude Code 2.1.220（更新于 2026-08-04），即模板内的行为约定以该版本前后的 Claude Code 交互模型为准。

如何安装 /push-all

按照 01-slash-commands/README.md 给出的安装方式，有两种落地路径（以下命令在你自己的项目中执行，而非修改本仓库）：

方式一：作为 Legacy Command（最快）

# 项目级（团队共享）
mkdir -p .claude/commands
cp push-all.md .claude/commands/

# 个人级
mkdir -p ~/.claude/commands
cp push-all.md ~/.claude/commands/

方式二：作为 Skill（官方推荐方向）

mkdir -p .claude/skills/push-all
cp push-all.md .claude/skills/push-all/SKILL.md

README 说明：自定义 slash commands 已并入 skills 体系，.claude/commands/ 下的文件仍然可用，但当同名 skill 与 command 同时存在时，skill 优先。安装后在 Claude Code 中输入 /push-all 即可触发。

七步工作流完整拆解

第 1 步：分析变更（并行执行）

模板要求 Claude 在一条消息中并行发出三条只读命令，为后续步骤收集上下文：

git status              # 显示 modified/added/deleted/untracked 文件
git diff --stat         # 显示变更统计（文件数、增删行数）
git log -1 --oneline    # 查看最近一次提交，用于对齐提交信息风格

这里 git log -1 --oneline 的用途值得注意：它不是可有可无的装饰，而是让生成的 commit message 在措辞和格式上"继承"项目已有的提交习惯，保证历史风格一致。

第 2 步：安全检查（Safety Checks）

这是 /push-all 区别于简单 git add . && git commit && git push 脚本的核心部分。模板规定，检测到以下任一项时必须立即停止并向用户告警：

类别	具体模式
Secrets（密钥文件）	.env*、*.key、*.pem、credentials.json、secrets.yaml、id_rsa、*.p12、*.p12、*.pfx、*.cer
API Keys	任何 *_API_KEY、*_SECRET、*_TOKEN 变量带有真实值（而不是占位符）
Large files	大于 10MB 且未使用 Git LFS 的文件
Build artifacts（构建产物）	node_modules/、dist/、build/、__pycache__/、*.pyc、.venv/
Temp files（临时文件）	.DS_Store、thumbs.db、*.swp、*.tmp

API Key 校验：模板进一步要求对修改后的文件做内容级模式检查，区分"真实密钥"与"占位符"：

OPENAI_API_KEY=sk-proj-xxxxx  # ❌ Real key detected!
AWS_SECRET_KEY=AKIA...         # ❌ Real key detected!
STRIPE_API_KEY=sk_live_...    # ❌ Real key detected!

# ✅ Acceptable placeholders:
API_KEY=your-api-key-here
SECRET_KEY=placeholder
TOKEN=xxx
API_KEY=<your-key>
SECRET=${YOUR_SECRET}

这个"真实值 vs 占位符"的判别规则很实用：示例配置（example env）里写 your-api-key-here 是安全的，而 sk-proj-、sk_live_、AKIA 这类前缀则是各厂商密钥的指纹特征，一旦出现即应阻断。

通过安全检查后，还需确认四个条件：

• .gitignore 已正确配置
• 当前无未解决的 merge conflicts
• 处于正确的分支（若当前在 main/master 上需给出警告）
• 所有 API key 均为占位符

第 3 步：请求确认（Confirmation Gate）

安全检查通过后，Claude 必须向用户呈现如下摘要模板，然后等待用户显式输入 yes 才允许继续：

📊 Changes Summary:
- X files modified, Y added, Z deleted
- Total: +AAA insertions, -BBB deletions

🔒 Safety: ✅ No secrets | ✅ No large files | ⚠️ [warnings]
🌿 Branch: [name] → origin/[name]

I will: git add . → commit → push

Type 'yes' to proceed or 'no' to cancel.

注意摘要中 Safety 一行要求把警告项（⚠️）如实列出——即使用户最终决定继续，他也能清楚知道哪些风险被带入了这次推送。模板用 "WAIT for explicit yes before proceeding." 这句话把确认语义写死，避免模型把含糊的"好的""嗯"当作批准。

第 4 步：执行暂存（确认后）

git add .
git status  # Verify staging

注意这里 git add . 之后紧跟一次 git status 用于"回读验证"暂存区内容与预期一致——这是防御性操作：git add . 的实际暂存范围以回读结果为准，而不是以命令本身的语义为准。

第 5 步：生成 Commit Message

模板要求分析变更内容并生成 Conventional Commits 格式的提交信息：

格式：

[type]: Brief summary (max 72 characters)

- Key change 1
- Key change 2
- Key change 3

类型（Types）： feat、fix、docs、style、refactor、test、chore、perf、build、ci

示例：

docs: Update concept README files with comprehensive documentation

- Add architecture diagrams and tables
- Include practical examples
- Expand best practices sections

这套类型表与同目录 commit.md（/commit 命令）中约定的子集（feat/fix/docs/refactor/test/chore）是一致的，/push-all 只是扩展到了完整的 Conventional Commits 类型集，说明两个命令共享同一套提交信息规范。

第 6 步：提交并推送

git commit -m "$(cat <<'EOF'
[Generated commit message]
EOF
)"
git push  # If fails: git pull --rebase && git push
git log -1 --oneline --decorate  # Verify

三个细节：

• 使用 here-doc（$(cat <<'EOF' ... EOF)） 传参，而不是 git commit -m "..." 双引号拼接——多行提交信息（标题 + 要点列表）在 shell 中经 here-doc 传递可以原样保留换行和缩进，且单引号 'EOF' 阻止了内容中的 $、反引号被 shell 二次展开，这对包含特殊字符的提交信息是必要的安全写法。
• git push 失败时的兜底策略是 git pull --rebase && git push，用 rebase 而非 merge 解决"远端有新提交"的常见冲突，避免产生多余的 merge commit。
• 最后用 git log -1 --oneline --decorate 回读验证提交确实落在目标分支的引用上。

第 7 步：确认成功

推送完成后，Claude 按固定模板向用户汇报结果：

✅ Successfully pushed to remote!

Commit: [hash] [message]
Branch: [branch] → origin/[branch]
Files changed: X (+insertions, -deletions)

固定汇报格式让每次推送结果可被快速比对：提交哈希、分支映射、文件与行数统计一目了然。

错误处理（Error Handling）

模板为三类失败场景分别给出了处理策略：

• git add 失败：检查文件系统权限、被锁定的文件，确认仓库已初始化（git init）。
• git commit 失败：修复 pre-commit hooks；检查 git config 中是否配置了 user.name / user.email。
• git push 失败，按原因细分：
  • Non-fast-forward（远端领先）：git pull --rebase && git push
  • 无远程分支：git push -u origin [branch] 建立上游跟踪
  • 受保护分支：不要强推，改用 PR 流程

何时使用、何时回避

模板给出了明确的适用性边界：

✅ 适合（Good）：

• 多文件的文档更新
• 带测试和文档的完整功能提交
• 跨多个文件的 bug 修复
• 全项目范围的格式化/重构
• 配置类变更

❌ 应避免（Avoid）：

• 不清楚自己到底要提交什么时
• 工作区包含 secrets 或敏感数据
• 面向受保护分支且未经评审
• 存在未解决的 merge 冲突
• 期望获得细粒度（granular）的提交历史
• pre-commit hooks 本身正在失败

替代方案：当用户需要更细的控制

模板最后一节提醒：如果用户希望保留控制权，应主动建议替代路径，而不是一味执行 /push-all：

1. Selective staging（选择性暂存）：审查并只 stage 特定文件；
2. Interactive staging（交互式暂存）：用 git add -p 按 patch 粒度选择；
3. PR workflow：创建分支 → 推送 → 提 PR，即使用仓库中的 /pr 命令（见 pr.md，它会先跑 lint 和测试、审查 diff 再生成 PR 摘要）。

模板以一句总结收尾："Always review changes before pushing. When in doubt, use individual git commands for more control."（推送前务必审查变更；拿不准时，用单独的 git 命令以获得更细的控制。）

仓库纵深佐证：Hook 层如何为"提交推送"补上第二道防线

/push-all 的安全检查依赖模型按清单执行，属于"软约束"。claude-howto 仓库的 06-hooks/ 模块提供了由 Claude Code 钩子机制强制执行的"硬约束"，两者结合构成完整的提交前防线：

1. 提交前跑测试：pre-commit.sh

该脚本挂在 PreToolUse（matcher: Bash）事件上，检测 Bash 命令是否为 git commit 后运行项目测试（自动识别 Node/pytest/Go/Rust 项目）。从源码结构看，它的注释特别强调了一个 Claude Code Hook 的关键协议细节：

# Exit codes: 2 blocks the tool call and surfaces stderr as the block reason.
# Any other non-zero value is a NON-blocking error — the commit would proceed.

即 只有退出码 2 才能真正阻断这次提交，其他非零值只是非阻塞报错、提交仍会继续。这意味着如果你要写类似的守卫脚本，测试失败时必须 exit 2 并把原因写到 stderr，否则防线形同虚设——这是把 Hooks 与 /push-all 组合使用时最容易踩的坑。

2. 写文件即扫密钥：security-scan.sh

该脚本挂在 PostToolUse（matcher: Write）事件上，在每次文件写入后扫描硬编码密码、API key、私钥（含 AKIA[0-9A-Z]{16} 的 AWS key 指纹）、以及在可用时调用 semgrep / trufflehog 深度扫描。发现疑似密钥时，它通过 hookSpecificOutput.additionalContext 以非阻塞警告的形式把问题注入 Claude 的上下文，提醒"改用环境变量"。

从两者的分工可以推断仓库作者的设计意图：security-scan.sh 在写盘阶段就拦截密钥进入文件，pre-commit.sh 在提交阶段拦截未过测试的代码，而 /push-all 的安全清单则是推送阶段的最后一道人工+模型复核。三层约束分别对应"文件 → 提交 → 远程"的泄漏路径，单独使用 /push-all 只覆盖了第三层。

小结

/push-all 模板的价值不在于它执行了 git add . && git commit && git push，而在于它把一件危险的事拆成了七个可审计的步骤：并行收集上下文（status/diff/log）、五类安全检查 + 密钥内容级判别、固定格式的确认摘要与显式 yes 门禁、here-doc 传参的多行提交、rebase 兜底与回读验证。把它与仓库中的 06-hooks/pre-commit.sh 测试守卫、06-hooks/security-scan.sh 密钥扫描组合使用，并在"拿不准时退回到 git add -p 或 /pr 流程"的自觉下运行，才能在享受一键推送效率的同时把误提交密钥、误推保护分支的风险压到最低。