Back to Details

local-merge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/local-merge

/local-merge

Merge a branch into a target branch via a disposable shallow clone, then propagate to the primary worktree non-destructively. Defaults to main if no target specified.
通过一次性浅克隆将分支合并到目标分支，然后无损同步到主工作区。若未指定目标分支，默认使用main。

Inputs

输入项

InputRequiredDefaultExample
BRANCH
yes—
feat/local-merge-skill
TARGET
no
main
develop
, 
release/v2
PRIMARY
noFirst line of 
git worktree list
/Users/you/projects/repo
MESSAGE
no
merge: $BRANCH into $TARGET
merge: feat/auth into main
输入项是否必填默认值示例
BRANCH
是—
feat/local-merge-skill
TARGET
否
main
develop
, 
release/v2
PRIMARY
否
git worktree list
的第一行
/Users/you/projects/repo
MESSAGE
否
merge: $BRANCH into $TARGET
merge: feat/auth into main

Phase 1 — Remote Merge (mechanical)

阶段1 — 远程合并（机械操作）

All commands are explicit. No reasoning required.
所有命令均为显式执行，无需推理。

1a. Calculate clone depth

1a. 计算克隆深度

bash
git fetch origin "$TARGET" "$BRANCH"
DEPTH=$(( $(git rev-list --count origin/"$TARGET"..origin/"$BRANCH") + 10 ))
bash
git fetch origin "$TARGET" "$BRANCH"
DEPTH=$(( $(git rev-list --count origin/"$TARGET"..origin/"$BRANCH") + 10 ))

1b. Clone, merge, push

1b. 克隆、合并、推送

bash
MERGE_DIR="${CLAUDE_SESSION_DIR:-/tmp}/local-merge-$$"
[ -d "$MERGE_DIR" ] && rm -rf "$MERGE_DIR"
git clone --depth "$DEPTH" --branch "$TARGET" "$(git remote get-url origin)" "$MERGE_DIR"

git -C "$MERGE_DIR" fetch origin "$BRANCH"
git -C "$MERGE_DIR" merge FETCH_HEAD -m "$MESSAGE"
git -C "$MERGE_DIR" push
bash
MERGE_DIR="${CLAUDE_SESSION_DIR:-/tmp}/local-merge-$$"
[ -d "$MERGE_DIR" ] && rm -rf "$MERGE_DIR"
git clone --depth "$DEPTH" --branch "$TARGET" "$(git remote get-url origin)" "$MERGE_DIR"

git -C "$MERGE_DIR" fetch origin "$BRANCH"
git -C "$MERGE_DIR" merge FETCH_HEAD -m "$MESSAGE"
git -C "$MERGE_DIR" push

1c. Non-fast-forward recovery

1c. 非快进恢复

bash
git -C "$MERGE_DIR" pull --rebase
git -C "$MERGE_DIR" push
Max 3 retries. After 3 failures, stop and report. Do not force-push.
bash
git -C "$MERGE_DIR" pull --rebase
git -C "$MERGE_DIR" push
最多重试3次。3次失败后停止并上报，禁止强制推送。

1d. Cleanup

1d. 清理

Always runs after Phase 1, success or failure:
bash
rm -rf "$MERGE_DIR"
无论阶段1成功或失败，都会执行此步骤：
bash
rm -rf "$MERGE_DIR"

Phase 2 — Propagate to Primary (reasoning required)

阶段2 — 同步到主工作区（需推理）

Bring the primary worktree's 
$TARGET
up to date with the newly-pushed remote. Steps 2a-2c are mechanical. Step 2d requires agent judgment. Steps 2e-2g depend on that judgment.
将主工作区的
$TARGET
分支与新推送的远程分支同步。步骤2a-2c为机械操作，步骤2d需要Agent判断，步骤2e-2g取决于该判断结果。

2a. Guard: is primary on TARGET?

2a. 检查：主工作区是否在TARGET分支？

bash
git -C "$PRIMARY" branch --show-current
Not on 
$TARGET
? Stop. Report: "Primary is on 
<branch>
, not 
$TARGET
. Remote updated; local not forwarded." Done.
bash
git -C "$PRIMARY" branch --show-current
不在
$TARGET
分支？停止操作。 上报：“主工作区当前在
<branch>
分支，而非
$TARGET
分支。远程分支已更新；本地未同步。”操作结束。

2b. Protect dirty state

2b. 保护未提交状态

bash
git -C "$PRIMARY" status --porcelain
If output is non-empty, shelter uncommitted work:
bash
git -C "$PRIMARY" add -A
git -C "$PRIMARY" commit -m "wip: preserve local state before remote sync"
Record 
WIP_CREATED=true
for step 2g. If clean, skip.
bash
git -C "$PRIMARY" status --porcelain
若输出非空，保存未提交工作：
bash
git -C "$PRIMARY" add -A
git -C "$PRIMARY" commit -m "wip: preserve local state before remote sync"
记录
WIP_CREATED=true
以便步骤2g使用。若工作区干净，跳过此步骤。

2c. Fetch updated TARGET

2c. 获取更新后的TARGET分支

bash
git -C "$PRIMARY" fetch origin "$TARGET"
bash
git -C "$PRIMARY" fetch origin "$TARGET"

2d. Analyze divergence (agent reasoning)

2d. 分析分歧（Agent推理）

Run all five commands, then assess using the decision matrix:
bash
git -C "$PRIMARY" rev-list --count HEAD..origin/"$TARGET"    # commits behind
git -C "$PRIMARY" rev-list --count origin/"$TARGET"..HEAD     # commits ahead
git -C "$PRIMARY" diff HEAD..origin/"$TARGET" --stat          # changed files
git -C "$PRIMARY" log HEAD..origin/"$TARGET" --oneline        # incoming commits
git -C "$PRIMARY" log origin/"$TARGET"..HEAD --oneline        # local-only commits
BehindAheadAssessmentAction
N > 00Fast-forward
--ff-only
(2e)
N > 0M > 0DivergedInspect diff for file overlap + semantic risk (2e)
00Already currentSkip, report, done
0M > 0Local-only commitsUnexpected — escalate to copilot (2f)
Beyond textual conflicts, assess semantic risk: two agents editing related config in different files can silently break things even when git sees no conflict.
执行以下五条命令，然后根据决策矩阵评估：
bash
git -C "$PRIMARY" rev-list --count HEAD..origin/"$TARGET"    # 落后的提交数
git -C "$PRIMARY" rev-list --count origin/"$TARGET"..HEAD     # 超前的提交数
git -C "$PRIMARY" diff HEAD..origin/"$TARGET" --stat          # 变更文件统计
git -C "$PRIMARY" log HEAD..origin/"$TARGET" --oneline        # 待合并提交记录
git -C "$PRIMARY" log origin/"$TARGET"..HEAD --oneline        # 本地独有提交记录
落后数超前数评估结果操作
N > 00可快进
--ff-only
（步骤2e）
N > 0M > 0分支分歧检查文件重叠情况及语义风险（步骤2e）
00已同步跳过，上报结果，操作结束
0M > 0本地独有提交异常情况 — 升级至Copilot处理（步骤2f）
除了文本冲突外，还需评估语义风险：两个Agent编辑不同文件中的相关配置时，即使Git未检测到冲突，也可能导致静默故障。

2e. Execute merge

2e. 执行合并

Fast-forward (behind > 0, ahead = 0):
bash
git -C "$PRIMARY" merge --ff-only origin/"$TARGET"
Non-conflicting divergence (different files, low semantic risk):
bash
git -C "$PRIMARY" merge origin/"$TARGET" --no-edit
If merge produces conflicts, abort immediately:
bash
git -C "$PRIMARY" merge --abort
Then escalate to copilot (2f).
Uncertain or risky: do not attempt merge. Go to 2f.
快进合并（落后数>0，超前数=0）：
bash
git -C "$PRIMARY" merge --ff-only origin/"$TARGET"
无冲突分歧（变更文件不同，语义风险低）：
bash
git -C "$PRIMARY" merge origin/"$TARGET" --no-edit
若合并产生冲突，立即终止：
bash
git -C "$PRIMARY" merge --abort
然后升级至Copilot处理（步骤2f）。
不确定或高风险：不尝试合并，直接进入步骤2f。

2f. Copilot escalation

2f. 升级至Copilot

  1. Invoke 
    /copilot
    to enter copilot mode
  2. Present the analysis from 2d: behind/ahead counts, diff stat, commit logs
  3. State what blocked automatic resolution
  4. Let the user drive the merge
  5. When resolved, invoke 
    /autonomous
    to restore previous mode
  1. 调用
    /copilot
    进入协作模式
  2. 提交步骤2d的分析结果：落后/超前提交数、差异统计、提交日志
  3. 说明阻止自动解决的原因
  4. 由用户主导合并操作
  5. 问题解决后，调用
    /autonomous
    恢复之前的模式

2g. Restore WIP state

2g. 恢复WIP状态

Only if 
WIP_CREATED=true
:
bash
git -C "$PRIMARY" reset --soft HEAD~1
Preserves all changes in the index and working tree exactly as they were before the skill ran.
仅当
WIP_CREATED=true
时执行：
bash
git -C "$PRIMARY" reset --soft HEAD~1
精确保留索引和工作区在本Skill运行前的所有变更。

Safety Invariants

安全准则

  • No force-push. Non-fast-forward retries use 
    pull --rebase
    , never 
    --force
    .
  • No work lost. Dirty state is WIP-committed before any merge, restored after.
  • No direct commits to main. Phase 1 uses a disposable clone for multi-agent isolation regardless of target. Phase 2 only fast-forwards or merges from origin.
  • Conflict = stop. Conflicts trigger 
    merge --abort
    and copilot escalation, never auto-resolution.
  • Cleanup always runs. The shallow clone is removed regardless of outcome.
  • 禁止强制推送。非快进重试使用
    pull --rebase
    ，绝不使用
    --force
    。
  • 无工作丢失。合并前将未提交状态通过WIP提交保存，操作后恢复。
  • 禁止直接向main提交。无论目标分支是什么，阶段1均使用一次性克隆实现多Agent隔离。阶段2仅从origin分支进行快进或合并。
  • 冲突即停止。冲突触发
    merge --abort
    并升级至Copilot，绝不自动解决。
  • 始终执行清理。无论结果如何，都会删除浅克隆目录。

Integration

集成场景

CallerContext
/ship
CI-down path after review approval
/reflect
Post-task consolidation to main
/copilot
Receives escalation from Phase 2f
/autonomous
Restored after copilot resolves conflict
调用者上下文
/ship
审核通过后的CI下游流程
/reflect
任务完成后合并至main分支
/copilot
接收阶段2f的升级请求
/autonomous
Copilot解决冲突后恢复自动模式