git-ops

Git 操作

智能 Git 操作编排器。为提高速度，将只读查询直接内联处理；将写入操作派发给后台 Sonnet Agent（git-agent），以释放主会话。

架构

User intent (commit, PR, rebase, status, etc.)
    |
    +---> Tier 1: Read-only (status, log, diff, blame)
    |       |
    |       +---> Execute INLINE via Bash (fast, no subagent)
    |
    +---> Tier 2: Safe writes (commit, push, tag, PR, stash)
    |       |
    |       +---> Gather context from conversation
    |       +---> Dispatch to git-agent (background, Sonnet)
    |       |       +---> Fallback: general-purpose with inlined protocol
    |       +---> Agent executes and reports back
    |
    +---> Tier 3: Destructive (rebase, reset, force-push, branch -D)
            |
            +---> Dispatch to git-agent (background, Sonnet)
            |       +---> Fallback: general-purpose with inlined protocol
            +---> Agent produces PREFLIGHT REPORT (does NOT execute)
            +---> Orchestrator relays preflight to user
            +---> On confirmation: re-dispatch with execute authority

安全等级

等级 1：只读 — 内联执行

无需子 Agent。通过 Bash 直接执行，立即获得结果。

操作	命令
状态（详细）	bash $HOME/.claude/skills/git-ops/scripts/status.sh — 一次性显示 HEAD、同步状态、目录树、工作树、分支和 PR
工作树概览	bash $HOME/.claude/skills/git-ops/scripts/worktree-survey.sh — 查看每个工作树的状态、检测偏差，并分类待清理/WIP/幽灵/孤立项目
全部合并计划	bash $HOME/.claude/skills/git-ops/scripts/land-all.sh [--porcelain] — 将每个分支归类为可合并/过期/WIP/活跃/已合并，以便批量合并（见下文“全部合并”）
状态（简略）	git status --short
日志	git log --oneline -20
差异（未暂存）	git diff --stat
差异（已暂存）	git diff --cached --stat
差异（完整）	git diff [file] 或 git diff --cached [file]
分支列表	git branch -v
远程分支	git branch -rv
储藏列表	git stash list
追溯	git blame [file]
显示提交	git show [hash] --stat
引用日志	git reflog --oneline -20
标签	git tag --list --sort=-v:refname
工作树列表	git worktree list
PR 列表	gh pr list
PR 状态	gh pr view [N]
Issue 列表	gh issue list
CI 检查	gh pr checks [N]
运行状态	gh run list --limit 5

对于 T1 操作，请整洁地格式化结果并直接呈现。有 delta 时，使用它显示差异。

何时使用附带的脚本：

• 用户询问“状态”“进展如何”“有什么需要提交”“有什么需要推送” → status.sh
• 用户询问工作树、可清理分支、偏差或“有什么可以清理” → worktree-survey.sh
• 两个脚本在状态正常时均以 0 退出，需要关注时以 1 退出，目录不是 Git 仓库时以 2 退出 — 可组合使用。

卫生检查（主动执行 — 每次 T1 状态检查时运行）

运行任何状态检查时，都要扫描以下反模式，并在状态输出之前指出。不要等用户发现。status.sh 脚本会自动处理检查 1 和 2；检查 3 和 4 由 Claude 负责。

反模式 1：主检出位于功能分支上 🔴

信号： 当前位于主检出目录（不是工作树），且 git branch --show-current ≠ 仓库的默认分支（main/master/trunk）。

危害： 主检出目录是备用工作区。功能分支留在这里会妨碍读取干净的状态、干扰工作树操作，还会让“当前”状态变得含糊。功能开发应放在专用工作树中。

标记方式： 在状态输出之前发出醒目的警告。

修复：

git checkout main                                              # return main to trunk
git worktree add .claude/worktrees/<name> <feature-branch>   # move work to worktree
# machine sets WORKTREE_ROOT? put it there instead: "$WORKTREE_ROOT/<repo>/<name>"

判断主检出还是工作树：

GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
# ".git"               → main checkout  → check applies
# contains "worktrees" → inside a worktree → skip this check

反模式 2：过期的已合并分支 🟡

信号： git branch --merged <default> 返回了主干分支以外的分支。

危害： 合并后未删除的分支会造成干扰，让人难以看清当前实际进行中的工作。

标记方式： 报告数量。建议使用 fleet sweep（fleet-ops）：其 --apply 会在输入确认后，零数据丢失地删除已合并、没有工作树且未被任何打开的会话占用的分支。

反模式 3：已推送分支上存在 WIP 提交 🟡

信号： git log --oneline @{u}..HEAD 中的提交主题行包含 wip|WIP|todo|TODO|fixme|FIXME|temp|TEMP|hack|HACK。

危害： 已推送历史中的 WIP 标记表明未完成的工作不应离开本地机器。这会造成混乱的历史记录，并妨碍创建整洁的 PR。

标记方式： 列出有问题的提交，并建议使用交互式变基进行合并或重命名。

反模式 4：大量未提交的更改 🟡

信号： 已暂存 + 未暂存 + 未跟踪文件 > 20 个。

问题： 大型未提交差异难以审查、容易丢失，也表明「边做边提交」的习惯出了问题。

标记： 记录总数，并建议按逻辑单元逐步提交。

---

第 2 级：安全写入——分派给 Agent

收集相关上下文，然后分派给 git-agent（后台运行，Sonnet）。

分派前收集上下文：

操作	需要收集的上下文
提交	用户正在处理的内容（来自对话）、已暂存文件、近期提交的风格
推送	当前分支、跟踪信息、领先于远程分支的提交
创建 PR	分支上相对于 main 的所有提交、用于编写描述的对话上下文
标签/发布	自上一个标签以来的提交、当前使用的版本模式
储藏	当前更改、用户提供的储藏说明（如果有）
挑选提交	目标提交详情、当前分支
创建分支	基础分支、近期分支采用的命名约定
gh issue 创建	用户描述、提及的标签

分派模板：

You are the git-agent handling a Tier 2 (safe write) operation.

## Domain Knowledge
For release or PR operations, read CI context first:
- Read: skills/ci-cd-ops/SKILL.md (release workflows, PR conventions)

## Context
- Current branch: {branch}
- Repository: {repo info}
- User intent: {what the user asked for}
- Conversation context: {relevant summary of what was being worked on}

## Operation
{specific operation details}

## Project Conventions
{commit style, branch naming, PR template if detected}

Execute the operation following your T2 protocol (verify state, execute, confirm, report).

第 3 级：破坏性操作——必须预检

分派给 git-agent，并明确要求仅生成预检报告。

分派模板（预检）：

You are the git-agent handling a Tier 3 (destructive) operation.

## Context
- Current branch: {branch}
- Repository: {repo info}
- User intent: {what the user asked for}

## Operation
{specific operation details}

IMPORTANT: Do NOT execute this operation. Produce a T3 Preflight Report only.
Show exactly what will happen, what the risks are, and how to recover.

用户确认后： 重新分派，并授予执行权限：

User has confirmed the Tier 3 operation after reviewing the preflight.

## Approved Operation
{exact operation from preflight}

## Confirmation
Proceed with execution. Follow T3 execution protocol:
1. Create a safety bookmark: note the current HEAD hash
2. Execute the operation
3. Verify the result
4. Report with the safety bookmark for recovery

分派机制

对于 T2/T3，默认在后台运行；用户正在等待结果时则在前台运行；仅在用户要求时隔离 worktree。调用方式：references/dispatch.md。

回退方案：git-agent 不可用时

如果 git-agent 不可用，则将任务分派给 general-purpose，并在提示词中内嵌层级协议；直接执行仅作为简单 T2 操作的最后手段。模板：references/dispatch.md。

扩展操作

发布工作流

git-ops 仅负责发布的本地部分——分析提交、生成 CHANGELOG 内容、创建本地标签。远程部分（推送、gh release create、仓库元数据）属于 github-ops 技能。

用户要求「创建发布」「提升版本」或「创建发布标签」时：

1. 直接执行（T1）： 检查当前版本以及自上一个标签以来的提交

   git describe --tags --abbrev=0 2>/dev/null
   git log --oneline $(git describe --tags --abbrev=0 2>/dev/null)..HEAD
   

2. 确定版本递增幅度：

   • feat: 提交 -> 次版本号递增
   • fix: 提交 -> 修订版本号递增
   • BREAKING CHANGE: 或 !: -> 需要用户明确批准（绝不自动提升主版本号）
   • 或使用用户指定的版本

3. 分派给 git-agent（T2）： 生成 CHANGELOG 内容 + 创建本地标签。

4. 将任务交接给 github-ops 以处理远程部分：推送提交、推送标签、附带说明创建 GitHub 发布；必要时更新仓库元数据。不要从 git-ops 调用 gh release create——这会跨越本地/远程边界。参见 skills/github-ops/SKILL.md 中的 update 模式。

其他扩展操作

生成 Changelog、完整 PR 流程、清理分支（删除分支属于 T3 预检）、semver 分析和冲突解决支持：references/extended-operations.md。

Worktree 操作

Worktree 在此技能中属于一等公民。分类如下：

操作	层级	方式
调查	T1	bash scripts/worktree-survey.sh — 只读，报告每个 worktree 的状态和偏差
新建 lane	T2（内联）	bash scripts/new-lane.sh [--sibling] <slug> [base] — 快速脚本化配置：在机器设置了 WORKTREE_ROOT 时，于 $WORKTREE_ROOT/<repo>/<slug> 创建分支 lane/<slug>；否则在仓库内的 .claude/worktrees/<slug> 创建（已加入 gitignore；使用 --sibling 可改为在仓库外创建 <repo>-<slug>），并带上被 gitignore 的环境文件。解决冲突的一键方案 — 见下文“Lane 配置”
创建（定制）	T2	通过 Agent 执行 git worktree add <path> -b <branch> — 用于脚本未涵盖的非标准布局
合并	T2	将 worktree 分支变基到主干 + 测试 + 快进。多步骤流程 — 见下文“Worktree 合并流程”
清理（干净）	T2	对幽灵条目（已注册但文件系统中不存在）运行 git worktree prune。始终安全，不会丢失数据
移除	T3	git worktree remove <path> — 会销毁文件系统状态。每个 worktree 都必须先完成预检并明确确认

Lane 配置（冲突解决方案）

bash scripts/new-lane.sh [--sibling] <slug> [base]：在 $WORKTREE_ROOT/<repo>/<slug>（设置了机器级根目录时）或 .claude/worktrees/<slug>（确保已加入 gitignore）创建分支 lane/<slug>，带上环境文件，绝不覆盖已有内容。已提交的 lane 工作不会因删除 worktree 而丢失；应尽早合并。详情：references/lane-provisioning.md。

先调查的纪律

未先运行 scripts/worktree-survey.sh 并向用户展示输出前，绝不建议执行 prune/remove。调查会将每个 worktree 分类为：

• (trunk) — 主仓库本身，绝不 prune
• PRUNABLE — 已合并到主干、没有未提交的工作、没有未推送的提交 → 可安全移除
• has WIP — 有未提交的更改 → 先提交或暂存，绝不自动移除
• unpushed — 有领先于上游的提交 → 移除前先推送或 cherry-pick
• in-flight — 尚未合并，也没有未提交更改 → 可能仍在使用中
• GHOST — 已注册但文件系统目录已不存在 → 运行 git worktree prune 修复
• UNREGISTERED / 孤立项 — 有文件系统目录但没有 git 条目 → 未经明确审查，切勿触碰

一轮并行 lane 结束后，改为运行 fleet sweep（fleet-ops）：它还能补充本调查无法获取的信息 — 已按内容合并的 lane、相互竞争的 lane、仍被打开的会话使用的孤立目录，以及应询问是否归档的已结束会话。

Worktree 合并流程（T2）

将 worktree 中的分支合并到主干（变基 + 测试 + 快进）：

1. 验证前置条件：worktree 干净、分支领先于主干、尚未合并
2. 获取主干，然后将 worktree 分支变基到主干上
3. 运行项目测试命令（从 package.json / pyproject.toml / justfile 中检测）
4. 测试通过后：将主干快进到变基后的提交
5. 不要推送 — 推送是单独的明确步骤（且应通过 push-preflight 执行）

将此任务作为 T2 操作分派给 git-agent，并提供 worktree 路径和主干名称。

全部合并 — 批量合并所有待处理 lane（T1 规划 → fleet-ops 执行）

使用 scripts/land-all.sh --porcelain 进行调查，在合并任何内容前，先与用户确认合并 / 搁置 / prune 计划（硬性规则），通过 fleet-ops 执行合并，遇到所有 CONFLICT 都升级处理，不要自行解决，然后先调查再清理。完整流程：references/land-all.md。

安全不变量： ACTIVE lane（有活跃的协作者写入者）绝不合并 — 这是应用于合并操作的 worktree 边界实时写入者防护。WIP 必须先明确提交。STALE 必须明确选择加入（使用 --recent-days 或指定分支名称）。默认只合并 LANDABLE。

边界（硬性规则）

参阅 rules/worktree-boundaries.md。摘要：

• 绝不执行 rm -rf .claude/worktrees/ 或 $WORKTREE_ROOT/<repo>/ ——调查中的孤立项计数仅供参考，绝不是清理提示
• 当 .claude/worktrees/ 中存在未跟踪条目时，绝不执行 git add -A（会将 gitlink 一并提交）
• 绝不擅自认定其他会话的工作树是“孤立的”——先询问
• 跨项目工作应保持跨项目；在操作仓库 Y 时，仓库 X 中的工作树绝不属于我们的处理范围

决策逻辑

收到与 git 相关的请求时，请遵循以下流程：

1. Classify the operation tier (T1/T2/T3)

2. If T1:
   - Execute inline via Bash
   - Format and present results
   - DONE

3. If T2:
   - Gather context (conversation, git state, conventions)
   - Decide foreground vs background:
     * User waiting on result? -> foreground
     * User continuing other work? -> background
   - Dispatch to git-agent with context
   - Relay result when received

4. If T3:
   - Gather context
   - Dispatch to git-agent for PREFLIGHT ONLY
   - Present preflight report to user
   - Wait for explicit confirmation
   - Re-dispatch with execute authority
   - Relay result

快速参考

任务	层级	内联/Agent
检查状态（详细）	T1	内联（scripts/status.sh）
工作树调查	T1	内联（scripts/worktree-survey.sh）
查看差异	T1	内联
查看日志	T1	内联
列出 PR	T1	内联
提交	T2	Agent
推送	T2	Agent
创建 PR	T2	Agent
创建标签	T2	Agent
创建发布	T2	Agent
暂存推送/弹出	T2	Agent
Cherry-pick	T2	Agent
创建分支	T2	Agent
创建工作树	T2	Agent
合并工作树	T2	Agent（变基 + 测试 + 快进）
清理幽灵工作树	T2	Agent（git worktree prune）
变基	T3	Agent（预检）
强制推送	T3	Agent（预检）
Reset --hard	T3	Agent（预检）
删除分支	T3	Agent（预检）
丢弃更改	T3	Agent（预检）
合并到 main	T3	Agent（预检）
移除工作树	T3	Agent（逐个工作树预检）

工具

工具	用途
git	所有 git 操作
gh	GitHub CLI——PR、议题、发布、操作
delta	语法高亮差异（如果可用）
lazygit	交互式 TUI（向用户推荐，不供 Agent 使用）

补充资源

如需了解详细模式，请加载：

• ./references/rebase-patterns.md - 交互式变基工作流与安全性
• ./references/stash-patterns.md - 暂存操作与工作流
• ./references/advanced-git.md - Bisect、cherry-pick、工作树、reflog、冲突
• ./references/dispatch.md - Agent 调用形式（后台、前台、工作树隔离），以及 git-agent 不可用时的回退方案
• ./references/extended-operations.md - 更新日志、完整 PR 周期、分支清理、semver 分析、冲突解决支持
• ./references/lane-provisioning.md - new-lane.sh 创建和强制执行的内容，以及 lane 工作的持久性
• ./references/land-all.md - 批量合并的完整说明：触发条件、状态表、fleet-ops 命令、冲突、清理