x-merge-branches
Merges a source branch into a target branch locally with configurable strategy (merge/squash/rebase), automatic conflict detection + rollback, and idempotent no-op when target already contains source HEAD. Centralizes the ~120 lines of inline Bash previously in x-implement-epic Phase 1.4e auto-rebase.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-merge-branches
- description
- Merges a source branch into a target branch locally with configurable strategy (merge/squash/rebase), automatic conflict detection + rollback, and idempotent no-op when target already contains source HEAD. Centralizes the ~120 lines of inline Bash previously in x-implement-epic Phase 1.4e auto-rebase.
- allowed-tools
- Bash, Read
- argument-hint
- --source <branch> --target <branch> [--strategy merge|squash|rebase] [--message <msg>] [--no-push]
- context-budget
- medium
- user-invocable
- true
- requires-capabilities
- []
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
Skill: Local Git Merge with Conflict Rollback (x-merge-branches)
Purpose
Single, idempotent entry point for merging one local branch into another with three strategies (merge / squash / rebase), automatic conflict detection and rollback, and a structured result payload. Replaces ~120 lines of inline Bash in x-implement-epic Phase 1.4e (auto-rebase between parallel stories + develop → epic/XXXX sync). Callers receive either {mergeSha, conflicts:false} or {conflicts:true, rolledBack:true, conflictedFiles:[...]} — never a half-merged working tree.
Triggers
/x-merge-branches --source develop --target epic/0049— defaultmergestrategy, push after success/x-merge-branches --source develop --target epic/0049 --strategy squash --message "sync develop"— squash with custom message/x-merge-branches --source feat/foo --target develop --strategy rebase— linear history via rebase/x-merge-branches --source develop --target epic/0049 --no-push— merge locally only
Parameters
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
--source |
string | Yes | — | Source branch to merge from. Must exist locally. |
--target |
string | Yes | — | Target branch that receives the merge. Must exist locally. |
--strategy |
enum | No | merge |
One of merge (default, git merge --no-ff), squash (git merge --squash + commit), rebase (git rebase). |
--message |
string | No | auto | Commit message for merge / squash. Ignored for rebase. Max 255 chars. |
--no-push |
boolean | No | false |
Skip git push origin <target> after a successful merge. |
Workflow
1. PARSE FLAGS -> extract --source, --target, --strategy, --message, --no-push
2. PRE-CHECKS -> working tree clean; source exists; target exists
3. CHECKOUT TARGET -> git checkout <target>
4. IDEMPOTENCY -> git merge-base --is-ancestor <source> <target> → noOp
5. ATTEMPT MERGE -> dispatch on strategy (merge | squash | rebase)
6. DECIDE -> success → capture mergeSha; conflict → abort + collect paths
7. PUSH (OPT) -> git push origin <target> when not --no-push and not noOp
8. EMIT RESULT -> structured JSON: mergeSha, conflicts, conflictedFiles, rolledBack, noOp
Step 1 — Parse Flags
SOURCE=""; TARGET=""; STRATEGY="merge"; MESSAGE=""; NO_PUSH="false"
while [ $# -gt 0 ]; do
case "$1" in
--source) SOURCE="$2"; shift 2 ;;
--target) TARGET="$2"; shift 2 ;;
--strategy) STRATEGY="$2"; shift 2 ;;
--message) MESSAGE="$2"; shift 2 ;;
--no-push) NO_PUSH="true"; shift ;;
*) echo "ERROR: unknown flag: $1" >&2; exit 1 ;;
esac
done
[ -z "$SOURCE" ] && { echo "ERROR: --source is required" >&2; exit 1; }
[ -z "$TARGET" ] && { echo "ERROR: --target is required" >&2; exit 1; }
case "$STRATEGY" in
merge|squash|rebase) ;;
*) echo "ERROR: INVALID_STRATEGY — must be merge|squash|rebase" >&2; exit 1 ;;
esac
Step 2 — Pre-Checks
# Working tree must be clean (RULE-004 preserves history; dirty tree risks loss)
if [ -n "$(git status --porcelain)" ]; then
echo "ERROR: WORKING_TREE_DIRTY — Working tree must be clean before merge" >&2
exit 1
fi
# Source branch must exist locally
if ! git rev-parse --verify --quiet "$SOURCE" >/dev/null; then
echo "ERROR: SOURCE_NOT_FOUND — Source branch '$SOURCE' not found" >&2
exit 2
fi
# Target branch must exist locally
if ! git rev-parse --verify --quiet "$TARGET" >/dev/null; then
echo "ERROR: TARGET_NOT_FOUND — Target branch '$TARGET' not found" >&2
exit 3
fi
Step 3 — Checkout Target
git checkout "$TARGET"
Step 4 — Idempotency (No-Op Check)
# If target already contains source HEAD, nothing to merge
if git merge-base --is-ancestor "$SOURCE" "$TARGET"; then
printf '{"mergeSha":null,"conflicts":false,"conflictedFiles":[],"rolledBack":false,"noOp":true}\n'
exit 0
fi
Step 5 — Attempt Merge (Dispatch on Strategy)
CONFLICTS="false"
case "$STRATEGY" in
merge)
if [ -n "$MESSAGE" ]; then
git merge --no-ff --no-edit -m "$MESSAGE" "$SOURCE" 2>/tmp/merge.err || CONFLICTS="true"
else
git merge --no-ff --no-edit "$SOURCE" 2>/tmp/merge.err || CONFLICTS="true"
fi
;;
squash)
if ! git merge --squash "$SOURCE" 2>/tmp/merge.err; then
CONFLICTS="true"
else
MSG="${MESSAGE:-squash: merge $SOURCE into $TARGET}"
git commit -m "$MSG" 2>/tmp/merge.err || CONFLICTS="true"
fi
;;
rebase)
git rebase "$SOURCE" 2>/tmp/merge.err || CONFLICTS="true"
;;
esac
Step 6 — Decide (Success or Conflict Rollback)
if [ "$CONFLICTS" = "true" ]; then
# Capture unmerged paths BEFORE aborting (diff-filter=U)
FILES=$(git diff --name-only --diff-filter=U 2>/dev/null | tr '\n' ' ' | sed 's/ $//')
CONFLICTED_FILES=$(printf '%s' "$FILES" | awk 'BEGIN{printf "["} \
{for(i=1;i<=NF;i++){if(i>1)printf ",";printf "\"%s\"",$i}} END{print "]"}')
# Abort the partial operation
ABORT_CMD="git merge --abort"
[ "$STRATEGY" = "rebase" ] && ABORT_CMD="git rebase --abort"
if ! $ABORT_CMD 2>/tmp/abort.err; then
echo "ERROR: ROLLBACK_FAILED — $ABORT_CMD failed; manual cleanup needed" >&2
cat /tmp/abort.err >&2
exit 11
fi
printf '{"mergeSha":null,"conflicts":true,"conflictedFiles":%s,"rolledBack":true,"noOp":false}\n' \
"$CONFLICTED_FILES"
exit 10
fi
MERGE_SHA=$(git rev-parse HEAD)
Step 7 — Optional Push
if [ "$NO_PUSH" != "true" ]; then
git push origin "$TARGET" || {
echo "WARN: push failed; merge is committed locally but not pushed" >&2
}
fi
Step 8 — Emit Structured Result
printf '{"mergeSha":"%s","conflicts":false,"conflictedFiles":[],"rolledBack":false,"noOp":false}\n' \
"$MERGE_SHA"
Outputs
| Field | Type | Always | Description |
|---|---|---|---|
mergeSha |
string(40) | null | Yes | SHA of the resulting merge / squash / rebase-HEAD commit; null on conflict or no-op |
conflicts |
boolean | Yes | true when any conflict was detected during the merge attempt |
conflictedFiles |
string[] | Yes | List of unmerged paths captured before rollback; [] on success / no-op |
rolledBack |
boolean | Yes | true when git merge --abort / git rebase --abort executed successfully |
noOp |
boolean | Yes | true when target already contained source HEAD (ancestor check) |
Error Codes
| Exit | Code | Condition | Message |
|---|---|---|---|
| 1 | WORKING_TREE_DIRTY |
git status --porcelain non-empty |
Working tree must be clean before merge |
| 1 | INVALID_STRATEGY |
--strategy not in {merge, squash, rebase} |
--strategy must be one of: merge, squash, rebase |
| 2 | SOURCE_NOT_FOUND |
source branch missing locally | Source branch '<name>' not found |
| 3 | TARGET_NOT_FOUND |
target branch missing locally | Target branch '<name>' not found |
| 10 | MERGE_CONFLICT_ROLLED_BACK |
conflict detected, rollback succeeded | Conflict in N files; merge aborted |
| 11 | ROLLBACK_FAILED |
git merge --abort / git rebase --abort failed |
Rollback failed; manual cleanup needed |
Error Handling
| Scenario | Action |
|---|---|
--source or --target missing |
exit 1; print usage hint |
--strategy invalid |
exit 1 INVALID_STRATEGY; print accepted values |
| Dirty working tree | exit 1 WORKING_TREE_DIRTY; no side effects |
| Source/target branch missing | exit 2 / 3 with suggestion git fetch origin |
| Target already contains source HEAD | exit 0 with noOp:true; no commit, no push |
| Conflict during merge/squash/rebase | capture conflictedFiles, abort, exit 10 MERGE_CONFLICT_ROLLED_BACK |
git merge --abort / git rebase --abort fails |
exit 11 ROLLBACK_FAILED; stderr carried verbatim; manual cleanup |
git push fails |
WARN only; local merge is preserved; caller can retry push |
Examples
# Happy path — merge develop into epic/0049, push after
/x-merge-branches --source develop --target epic/0049
# -> {"mergeSha":"abc123...","conflicts":false,...,"noOp":false}
# No-op — target already contains source HEAD
/x-merge-branches --source develop --target epic/0049
# -> {"mergeSha":null,...,"noOp":true}
# Conflict with automatic rollback (exit 10)
/x-merge-branches --source develop --target epic/0049
# -> {"mergeSha":null,"conflicts":true,"conflictedFiles":["a.md"],"rolledBack":true,...}
# Squash with custom commit message
/x-merge-branches --source feat/foo --target develop --strategy squash --message "feat(foo): batch"
# Rebase feature branch onto develop (linear history, no push)
/x-merge-branches --source develop --target feat/foo --strategy rebase --no-push
Rule References
- Rule 09 (Branching Model) — merge-direction rules and target-branch conventions.
- RULE-004 (EPIC-0049 — Estratégia de merge: preserva history) — default strategy
mergewith--no-ffpreserves per-task TDD commits for bisect. - RULE-005 (EPIC-0049 — Thin orchestrator) —
x-implement-epicandx-implement-storydelegate local merges here; no inlinegit mergeblocks. - RULE-010 (EPIC-0049 — Skills internas pequenas) — this SKILL.md stays under 250 lines.
Integration Notes
| Skill | Relationship | Context |
|---|---|---|
x-implement-epic |
caller (future refactor — story-0049-0018) | Phase 1.4e auto-rebase between parallel stories; develop → epic/XXXX sync |
x-implement-story |
caller (future refactor — story-0049-0019) | Optional auto-sync of story branch with parent epic branch |
x-internal-ensure-epic-branch |
related (story-0049-0008) | Ensures epic/XXXX exists before this skill merges develop into it |
x-merge-pr |
sibling (story-0049-0003) | Remote PR merge via gh pr merge; this skill handles local-only merges |
x-create-git-branch |
sibling (story-0049-0001) | Bare branch creation; this skill assumes both branches exist |
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.