Claude Code Commit Commands 插件实战指南：用 /commit、/commit-push-pr、/clean_gone 自动化 Git 提交、推送与 Pull Request 全流程

本指南围绕 Claude Code 官方插件目录（claude-plugins-official）中的 Commit Commands 插件展开，深入讲解其提供的 /commit、/commit-push-pr、/clean_gone 三条斜杠命令：它们如何把「暂存文件 → 撰写提交信息 → 推送远端 → 创建 PR → 清理过期分支」这一整套 Git 工作流压缩为单条命令。读完本文，你将掌握每个命令的完整工作步骤、底层命令实现细节、权限配置原理，以及如何将它们嵌入日常开发与仓库维护流程，真正减少上下文切换与手工敲命令的次数。

插件概览：把多条 Git 命令压缩成一条斜杠命令

Commit Commands 插件由 Anthropic 官方维护（插件作者为 Anthropic，当前版本 1.0.0，采用 Apache License 2.0，见 插件许可证），定位是自动化常见 Git 操作、减少上下文切换和手工命令执行。插件共提供三条命令，覆盖提交、推送、建 PR、清理四条主线：

命令	一句话作用	依赖
/commit	分析工作区变更，自动生成符合仓库风格的提交信息并完成暂存与提交	仅需 Git
/commit-push-pr	一条命令完成「建分支 → 提交 → 推送 → 创建 PR」	Git + GitHub CLI（gh）
/clean_gone	清理远程已删除、本地仍残留的过期分支（含 worktree 分支）	仅需 Git

三个命令的定义文件位于 commands 目录：分别是 commit.md、commit-push-pr.md 和 clean_gone.md。插件根目录的 README.md 是官方使用文档，本文即以其为主体展开，并结合命令定义源码逐条剖析。

安装方式：随 Claude Code 插件市场一键启用

该插件是 Claude Code 官方插件目录（/plugins，由 Anthropic 内部维护）的一部分，按照仓库根目录 README.md 的说明，安装方式有两种：

# 方式一：直接指定插件名与市场名安装
/plugin install commit-commands@claude-plugins-official

# 方式二：在 Claude Code 中浏览插件市场
/plugin > Discover   # 搜索 commit-commands 并安装

插件安装后即被加载，其命令会自动出现在 Claude Code 的斜杠命令列表中，不需要额外配置。注意仓库根 README 同时提示：安装、更新或使用任何插件前请先确认其可信度——插件可能包含 MCP 服务器、文件或其他软件，Anthropic 无法逐一代为验证。

/commit：一条命令完成变更分析、暂存与提交

/commit 是最常用的日常提交命令，其核心价值在于：把「看状态 → 看 diff → 写信息 → git add → git commit」五步操作交给 Claude 一次性完成。

六个内部步骤

根据官方文档，/commit 的执行流程如下：

1. 分析当前 git status —— 了解工作区整体状态；
2. 同时审查已暂存与未暂存的变更（staged 与 unstaged）；
3. 查看最近提交记录，学习当前仓库的提交信息风格；
4. 起草一条合适的提交信息；
5. 暂存相关文件；
6. 创建提交。

命令实现细节：定义文件中的上下文注入与权限白名单

从 commit.md 的源码可以看到它的完整设计。文件头部是 YAML frontmatter：

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---

这里的 allowed-tools 是一个权限白名单，限制了本命令只能调用 Git 的 add、status、commit 三类操作，其他工具（如文件读写、网络请求）一律不被允许，从机制上把 /commit 约束为「纯 Git 操作」，避免 Claude 在提交过程中越权做无关动作。这是 Claude Code 命令 frontmatter 的推荐写法——按 frontmatter 参考文档 的建议，allowed-tools 应尽可能严格，并优先使用 Bash(git:*) 这类带命令过滤器的形式而非放开的 *。

命令正文通过反引号插值（Claude Code 的 !command`` 内联执行语法）在每次调用时动态注入上下文：

- Current git status: !`git status`
- Current git diff (staged and unstaged changes): !`git diff HEAD`
- Current branch: !`git branch --show-current`
- Recent commits: !`git log --oneline -10`

这四条命令正是「提交信息风格学习」的数据来源：git log --oneline -10 让 Claude 看到最近 10 条提交的写法，从而模仿仓库既有风格。任务描述则强调「基于以上变更创建单个 git 提交」，并明确要求 Claude 具备多工具并行调用能力时在一条消息内完成暂存与提交，不发送任何多余文本——这是为了让命令执行尽可能原子化、无副作用。

特性与安全边界

官方文档列出的 /commit 特性包括：

• 自动生成符合仓库风格的提交信息：通过学习 git log 历史模仿团队写法；
• 遵循 Conventional Commits 规范：默认按约定式提交格式起草信息；
• 避免提交含敏感信息的文件：如 .env、credentials.json 会被排除，防止密钥误入库；
• 提交信息中附带 Claude Code 归属标记（attribution），便于追溯提交来源。

典型使用

# 修改代码之后，直接运行：
/commit

# Claude 将会：
# - 审查你的变更
# - 暂存相关文件
# - 用恰当的信息创建提交
# - 向你展示提交状态

/commit-push-pr：提交、推送、创建 PR 一步到位

/commit-push-pr 面向「功能开发完成、准备开 PR」的时刻，把原本需要五六个命令串起来的工作合并为一条斜杠命令，是减少上下文切换的核心利器。

五个内部步骤

1. 创建新分支（若当前正处于 main 分支）；
2. 暂存并提交变更，使用恰当的提交信息；
3. 将分支推送到 origin；
4. 使用 gh pr create 创建 Pull Request；
5. 向用户提供 PR 链接。

命令实现细节：权限面更广、上下文更聚焦

从 commit-push-pr.md 的源码可见其 frontmatter 权限面比 /commit 更宽：

---
allowed-tools: Bash(git checkout --branch:*), Bash(git add:*), Bash(git status:*), Bash(git push:*), Bash(git commit:*), Bash(gh pr create:*)
description: Commit, push, and open a PR
---

白名单新增了三类能力：git checkout --branch:*（建分支）、git push:*（推送）、gh pr create:*（建 PR），恰好对应「分支管理 → 提交 → 推送 → PR」的完整链路。上下文注入则聚焦于状态与差异：

- Current git status: !`git status`
- Current git diff (staged and unstaged changes): !`git diff HEAD`
- Current branch: !`git branch --show-current`

任务描述同样强制「单消息完成」：在同一轮工具调用中依次执行建分支（若在 main 上）、创建单个提交、推送 origin、gh pr create，不调用任何其他工具、不发送任何多余文本。

特性与前置要求

官方文档列出的特性包括：

• 分析分支上的全部提交（而非只看最新一条），PR 描述能反映整个分支的变更全貌；
• 生成内容完整的 PR 描述，包含三部分：
  • 变更摘要（1～3 条要点 bullet points）；
  • 测试计划清单（test plan checklist）；
  • Claude Code 归属标记；
• 自动处理分支创建：检测到当前在 main 分支时会自动切出功能分支；
• 通过 GitHub CLI（gh）创建 PR。

前置要求（重要）：

• GitHub CLI（gh）必须已安装并完成身份认证（gh auth login）；
• 仓库必须存在名为 origin 的远端。

典型使用

# 完成你的修改后运行：
/commit-push-pr

# Claude 将会：
# - 按需创建功能分支
# - 提交你的变更
# - 推送到远端
# - 打开包含摘要和测试计划的 PR
# - 把 PR 链接交给你审阅

/clean_gone：一键清理远程已删除的本地过期分支

/clean_gone 解决的是 Git 仓库的「僵尸分支」问题：远程分支被合并删除后，本地分支仍以 [gone] 状态残留，日积月累会让 git branch 列表变得混乱。该命令负责安全地批量清理。

四个内部步骤

1. 列出所有本地分支，识别标记为 [gone] 的状态；
2. 识别与 [gone] 分支关联的 worktree 并移除；
3. 删除所有标记为 [gone] 的分支；
4. 反馈已删除的分支信息（若无需清理则明确报告）。

命令实现细节：完整的清理脚本

clean_gone.md 与其他两个命令不同，它不依赖 Claude 自主推断，而是直接给出了三步 bash 命令让 Claude 依次执行，确保结果可预期：

第 1 步：列出分支，识别 [gone] 状态

git branch -v

注意：带 + 前缀的分支表示有关联的 worktree，这类分支必须先移除 worktree 才能删除。

第 2 步：识别需要移除的 worktree

git worktree list

第 3 步：移除 worktree 并删除 [gone] 分支（同时处理普通分支与 worktree 分支）

# 处理所有 [gone] 分支，去掉可能存在的 '+' 前缀
git branch -v | grep '\[gone\]' | sed 's/^[+* ]//' | awk '{print $1}' | while read branch; do
  echo "Processing branch: $branch"
  # 查找并移除关联的 worktree（如存在）
  worktree=$(git worktree list | grep "\\[$branch\\]" | awk '{print $1}')
  if [ ! -z "$worktree" ] && [ "$worktree" != "$(git rev-parse --show-toplevel)" ]; then
    echo "  Removing worktree: $worktree"
    git worktree remove --force "$worktree"
  fi
  # 删除分支
  echo "  Deleting branch: $branch"
  git branch -D "$branch"
done

这段脚本的设计要点值得展开：

• grep '\[gone\]' 精确匹配 git branch -v 输出中状态列为 [gone] 的行；
• sed 's/^[+* ]//' 剥掉行首的分支标记符（+ 表示 worktree 分支、* 表示当前分支、空格是普通分支），统一提取分支名；
• awk '{print $1}' 取分支名字段；
• worktree 移除前会先校验：仅当 worktree 存在且不等于仓库根目录（git rev-parse --show-toplevel）时才 git worktree remove --force，避免误伤主工作区；
• 最后用 git branch -D（大写 D，强制删除）清理残留分支。

适用场景

• PR 合并并删除远程分支之后；
• 本地分支列表被过期分支塞满时；
• 常规仓库维护期间。

从源码看三个命令的工程实现要点

将三条命令的定义文件放在一起对比，可以归纳出这套插件值得借鉴的工程模式：

1. 权限最小化设计。 三个命令都通过 frontmatter 的 allowed-tools 严格限定可用工具：/commit 只有 git add/status/commit，/commit-push-pr 在此基础上增加 git checkout --branch、git push 与 gh pr create，/clean_gone 则完全不需要额外工具（其 description 字段即说明了用途，执行逻辑全部落在命令正文的脚本中）。这与 frontmatter 参考文档 中「能多严格就多严格、Bash 必须带命令过滤器」的最佳实践完全一致，既减少权限弹窗打扰，也从源头规避越权操作风险。

2. 上下文动态注入。 每个命令在被调用时都通过 !git ...`` 内联执行语法实时获取仓库状态（status、diff、分支、最近提交），保证 Claude 的决策始终基于当前真实状态，而非过期快照。这也是 Claude Code 命令开发的通用推荐模式（可参考 example-plugin 的示例命令 中的 $ARGUMENTS 与上下文写法）。

3. 单消息原子化执行。 三个命令的任务描述都明确要求「在同一轮消息中完成全部工具调用、不做任何多余动作、不发多余文本」，把「多步 git 操作」折叠成一次原子化动作，降低中途被打断或状态不一致的风险。

4. 确定性与智能化分层。 /clean_gone 属于确定性操作，直接给出完整脚本保证结果可控；/commit 与 /commit-push-pr 属于智能化操作，把「信息撰写」交给模型，同时用明确的步骤约束流程。这种「能脚本化就脚本化、需判断才交给模型」的分层思路，是该插件在可靠性与灵活性之间取得的平衡。

最佳实践：三个命令的正确用法

官方文档针对每条命令给出了使用建议：

使用 /commit：

• 提交前先审查暂存的变更；
• 让 Claude 分析你的变更并匹配仓库的提交风格；
• 可以信任自动生成的信息，但提交前应核对其准确性；
• 适合开发过程中的常规提交。

使用 /commit-push-pr：

• 在你准备好创建 PR 时使用；
• 确保所有变更完整且已测试；
• Claude 会分析整个分支历史来撰写 PR 描述；
• 创建后审阅 PR 描述，必要时手动编辑；
• 适合想最大限度减少上下文切换的场景。

使用 /clean_gone：

• 周期性运行以保持分支列表整洁；
• 在合并多个 PR 之后尤其有用；
• 可以放心运行——它只删除远程已删除的分支，不会误删仍有效的分支；
• 有助于维持本地仓库的整洁。

工作流整合：三种典型开发节奏

官方文档给出了三条命令的三种组合用法，覆盖日常开发、功能开发与维护三条主线：

快速提交工作流：

# 写代码
/commit
# 继续开发

功能分支工作流：

# 跨多个提交开发功能
/commit  # 第一次提交
# 更多修改
/commit  # 第二次提交
# 准备创建 PR
/commit-push-pr

维护工作流：

# 多个 PR 合并之后
/clean_gone
# 工作区清爽，迎接下一个功能

环境要求

• 必须安装并配置好 Git；
• 使用 /commit-push-pr 时：GitHub CLI（gh）必须安装且完成认证；
• 仓库必须是带有远端（remote）的 Git 仓库，其中 /commit-push-pr 要求远端名为 origin。

故障排查

官方文档针对三个常见问题给出了排查指引：

/commit 创建了空提交

• 原因：没有可提交的变更；
• 解决：确认存在未暂存或已暂存的变更，运行 git status 验证变更确实存在。

/commit-push-pr 创建 PR 失败

• 原因：gh pr create 命令执行失败；
• 解决：
  • 安装 GitHub CLI（macOS 可用 brew install gh，其他平台请使用对应系统的包管理器安装）；
  • 执行 gh auth login 完成认证；
  • 确认仓库的远端指向 GitHub 仓库。

/clean_gone 找不到可清理的分支

• 原因：没有标记为 [gone] 的分支；
• 解决：先运行 git fetch --prune 更新远程跟踪信息——只有分支在远程被删除后，本地才会显示为 [gone]。

实用技巧与总结

官方 Tips 章节给出了四点实战建议，与前述最佳实践相互印证：

• 与其他工具配合：开发过程中用 /commit 高频提交，准备就绪时用 /commit-push-pr 一步开 PR；
• 让 Claude 起草提交信息：提交信息分析会学习你仓库的既有风格，用得越多越贴合团队习惯；
• 定期清理：建议每周运行一次 /clean_gone，维持分支列表干净；
• 推送前审阅：推送之前始终检查提交信息与变更内容。

总的来说，Commit Commands 插件把 Git 日常高频操作抽象成了三个语义清晰的斜杠命令，配合 allowed-tools 权限白名单与「单消息原子化」的执行约束，在自动化程度与操作安全性之间做了很好的取舍。对于任何重度使用 Claude Code 的开发者，这套插件都是减少上下文切换、规范提交与 PR 流程的实用选择；对于插件开发者，其命令定义文件（commit.md、commit-push-pr.md、clean_gone.md）本身也是学习 Claude Code 命令 frontmatter、上下文注入与权限控制的最佳范本。