claude-howto 中 /push-all 命令详解：带安全检查与确认门禁的 Git 提交推送 Slash Command 模板
【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto
本文以 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.
从设计上看，这条命令有三个关键决策：
allowed-tools最小权限白名单：只放行git add / status / commit / push / diff / log / pull七个只读或提交类的 git 子命令模式，其余 Bash 调用（如rm、curl、任意脚本）都需要额外授权。这是把"能做什么"收敛到"只该做什么"的第一道防线。- 显式确认门禁（Confirmation Gate）：模板要求 Claude 在执行
git add .之前，必须先向用户展示变更摘要并等待输入yes才能继续。命令的"自动化"止步于确认点，人保留最终决定权。 - 推送前安全检查：把密钥泄露、大文件、构建产物、临时文件等典型"误提交"场景全部列成检查清单，要求逐条过筛后才允许进入暂存阶段。
该模板在 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.mdREADME 说明：自定义 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 explicityesbefore 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 流程
- Non-fast-forward（远端领先）：
何时使用、何时回避
模板给出了明确的适用性边界：
✅适合（Good）：
- 多文件的文档更新
- 带测试和文档的完整功能提交
- 跨多个文件的 bug 修复
- 全项目范围的格式化/重构
- 配置类变更
❌应避免（Avoid）：
- 不清楚自己到底要提交什么时
- 工作区包含 secrets 或敏感数据
- 面向受保护分支且未经评审
- 存在未解决的 merge 冲突
- 期望获得细粒度（granular）的提交历史
- pre-commit hooks 本身正在失败
替代方案：当用户需要更细的控制
模板最后一节提醒：如果用户希望保留控制权，应主动建议替代路径，而不是一味执行/push-all：
- Selective staging（选择性暂存）：审查并只 stage 特定文件；
- Interactive staging（交互式暂存）：用
git add -p按 patch 粒度选择； - 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流程"的自觉下运行，才能在享受一键推送效率的同时把误提交密钥、误推保护分支的风险压到最低。
【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
