SuperAPI AI Directory

integrate-branches

Coding & development

View repository

Updated 10-15 16:53

About this skill

Skill: Integrate Branches

Purpose

Batch-finalize feature branches in the main repository: scan all active linked worktrees and local branches without worktrees, let the user choose which ones to land, verify each workspace is clean one by one, merge + push in sequence, and finally clean up all successfully merged worktrees. This saves the operation of entering each cd directory and manually delivering one by one.


Core Objective

Primary objective: On the main branch of the main repository, merge the user-selected branches (from worktrees or standalone branches) into main, push to origin, and clean up the successful worktrees—leaving the repository in a known clean state.

Success criteria(all must be satisfied):

  1. ✅ Invocation context verified: CWD is the main repository root (not inside a linked worktree), and the current branch is the main branch
  2. ✅ All candidates discovered:git worktree list --porcelain and git branch are both resolved; non-main entries are presented to the user in a unified list with type identifiers
  3. ✅ Prechecks completed before any merge: all selected worktree entries have been checked for a clean workspace; all dirty entries are reported together in one block
  4. ✅ Sequential merge + push: each selected clean branch is in turn merged with --no-ff and pushed; status is recorded one by one (succeeded / failed)
  5. ✅ Unified cleanup: all succeeded worktree entries are removed together; branch-only entries skip worktree removal; failed entries are not cleaned up at all
  6. ✅ Summary report output: merge / push / cleanup / branch deletion status is covered for each branch

Acceptance test: After the skill finishes executing,git log --oneline <main-branch> has one merge commit for each successful branch;git worktree list only the main repository plus failed/skipped worktree entries remain;git ls-remote origin <main-branch> is consistent with local.


Scope Boundaries

This skill is responsible for:

  • Verifying the invocation context (main repository root + main branch)
  • Determining the main branch (auto-detect; only ask the user when it cannot be determined)
  • Scanning linked worktrees (git worktree list --porcelain) and local branches without worktrees (git branch)
  • Deduplication: branches already covered by worktree entries are not shown again
  • User multi-selects branches to merge (all or a subset by index)
  • Prechecking workspaces: worktree entries use git -C <path> status --porcelain; branch-only entries skip the dirty check (no separate workspace)
  • For each selected branch, execute pull → --no-ff merge → push
  • After each failure, ask the user: continue with the remaining entries or abort
  • Unified cleanup of all successfully merged worktree entries (git worktree remove)
  • Optional feature branch deletion (user confirmation, only -d)
  • Per-branch summary report

This skill is not responsible for:

  • Single worktree delivery (please use inside the worktree deliver-feature)
  • Committing uncommitted changes (please first use inside each worktree commit-work)
  • Rebase or squash before merge
  • Resolving merge conflicts (stop and report to the user on conflict)
  • Creating or managing pull requests
  • Force pushing to any branch
  • Parallel merge execution (always executed sequentially)

Handoff point:

  • → deliver-feature: When the user, within a single worktree, only wants to deliver that branch without cd returning to the main repository
  • Stop and prompt the user: When invoked inside a linked worktree, or when invoked on a non-main branch in the main repository
  • When a branch has a merge conflict: Stop that one, ask whether to continue with the rest
  • When a branch push is rejected: Stop that one, ask whether to continue with the rest

Use Cases

  • A developer has 2–4 feature branches (some in worktrees, some as standalone branches) ready to land on main all at once
  • Batch wrap-up at the end of a sprint: merge, push, and clean up all completed feature branches in the main repository
  • CI / automation flows generated multiple parallel worktrees plus several topic branches, and now the results are being consolidated

Behavior

Workflow (Checklist)

Step 1 — Verify the invocation context

git rev-parse --git-dir              # 主仓库: <root>/.git ; linked worktree: <main-root>/.git/worktrees/<name>
git rev-parse --git-common-dir       # 两种上下文均返回同一值: <main-root>/.git
git rev-parse --abbrev-ref HEAD      # 当前分支
git rev-parse --show-toplevel        # 当前仓库根目录

linked worktree's git-dir != git-common-dir; in the main repository the two are equal.

  • If git rev-parse --git-dir and git rev-parse --git-common-dir differ (i.e., CWD is inside a linked worktree) → Stop:

    "This skill must be run from the root of the main repository, not from inside a worktree. Current location:<cwd>. To deliver the branch of the current worktree, use deliver-feature。"

  • If the current branch is not the detected main branch (Step 2) → Stop:

    "The current branch is <current-branch>, not <main-branch>. Please switch to the main branch first:git checkout <main-branch>。"

Record <main-repo>(= git rev-parse --show-toplevel). From then on, the CWD remains here for every step.

Step 2 — Determine the main branch

git remote show origin | grep 'HEAD branch'
  • Result is unambiguous (e.g., HEAD branch: main) → use it directly.
  • Command fails or returns no result → check git branch -r in origin/main, then check origin/master。
  • Still cannot determine → Ask the user:

    "Unable to automatically determine the main branch. Please enter the main branch name (e.g., main, master, develop):"

Record <main-branch>。

Step 3 — Scan and display selectable branches

# 来源 1:linked worktrees
git worktree list --porcelain

# 来源 2:所有本地分支
git branch --format='%(refname:short)'

Parse the porcelain output. The first worktree record is the main repository itself—skip it. Record each of the rest as a type: worktree candidate.

From the git branch output, exclude:

  • <main-branch> itself
  • Branches already covered by worktree entries (deduplicated by branch name)

Record the remaining branches as type: branch candidates (with no associated worktree path).

Build a unified list of {path, branch, type} tuples. Skip detached entries and mark them as unavailable.

  • No candidates → Stop:

    "No active linked worktrees or local branches found; nothing to integrate."

Display the list with index number, type identifier, path (if applicable), branch name, and most recent activity hint:

Available branches to integrate:
  [1]  worktree  /repos/myapp-auth      feat/user-auth      (last commit: 2 days ago)
  [2]  worktree  /repos/myapp-api       feat/api-v2         (last commit: 5 days ago)
  [3]  branch    —                      feat/dashboard      (last commit: 14 days ago — STALE)

Ask:

"Please select the branches to integrate, enter index numbers (comma-separated) or all:"

Record <selected-list>。

Step 4 — Pre-check: check all selected entries

For each entry <selected-list> in E:

  • If E.type == worktree:
    git -C <E.path> status --porcelain
    
  • If E.type == branch: no independent worktree — skip the dirty check, always treat as clean.

Collect the results separately into <clean-list> and <dirty-list>。

If <dirty-list> is non-empty, report all dirty entries uniformly before any merge begins:

Pre-flight check — dirty worktrees (will be skipped):
  /repos/myapp-api  (feat/api-v2)    — 3 uncommitted file(s)

Ask:

"The above worktrees have uncommitted changes. Continue merging the remaining clean entries, or halt everything? [continue / halt]"

  • halt → stop; do not perform any merges.
  • continue → continue only for <clean-list> . If <clean-list> is empty → stop and prompt "no actionable items".

Under no circumstances auto-stash.

Step 5 — Batch merge + push (executed sequentially)

For each entry <clean-list> in E:

# 多分支运行期间保持最新
git pull origin <main-branch>

# --no-ff 合并
git merge --no-ff <E.branch> -m "Merge branch '<E.branch>' into <main-branch>"

# 推送
git push origin <main-branch>

Keep CWD at <main-repo>。

When entry E fails:

  • Merge conflict:

    "Merge <E.branch> into <main-branch> resulted in a conflict. Please resolve the conflict in <main-repo> , complete the merge manually, then push and remove the worktree (if applicable)."

  • Push rejected (non-fast-forward):

    "After merging <E.branch> , the push was rejected. Please run <main-repo> in git reset --hard HEAD~1 to undo the merge, then pull, re-merge, and push."

In both cases, mark E as failed, and ask:

"Continue processing the remaining branches, or abort all remaining items? [continue / abort]"

  • abort → stop; do not process any remaining entries.
  • continue → mark E as failed, and continue with the next one.

Record the result for each entry:succeeded or failed。

Step 6 — Unified cleanup (worktree entries only)

After all merges are complete, confirm that CWD is still <main-repo>:

pwd   # 必须等于 <main-repo>

Only for entries in <succeeded-list> where E.type == worktree :

git worktree remove <E.path>

Execute sequentially. If a removal fails (e.g., the path no longer exists), record the error and continue with the next one.

type: branch entries have no worktree path — skip this step entirely. Never remove the worktree of a failed entry.

Step 7 — Offer local branch deletion option

For all entries in <succeeded-list> , display the branch list uniformly:

"Successfully cleaned entries. Delete the following local feature branches? Enter the number,all or none:"

[1]  feat/user-auth  (was worktree)
[2]  feat/dashboard  (was branch)

After each confirmation, execute:

git branch -d <E.branch>

Use only -d— never use -D. If -d fails, report the error and stop deleting that branch.

Step 8 — Summary report

integrate-branches summary
──────────────────────────────────────────────────────────────────────────
Type      Branch            Merge          Push   Cleanup  Branch-Del
worktree  feat/user-auth    ✓              ✓      ✓        deleted
worktree  feat/api-v2       ✗(conflict)    —      —        —
branch    feat/dashboard    ✓              ✓      —        deleted
──────────────────────────────────────────────────────────────────────────
Main repo: /repos/myapp · Main branch: main · Remote: origin

Status codes:✓ success · ✗(原因) failed · skipped(dirty) precheck failed · — not applicable

type: branch entries' Cleanup column is always —(no worktree to remove).


Input & Output

Input requirements

Input Required Description
Main repository + main branch context Yes CWD must be the main repository root, and the current branch must equal the main branch
Active candidates Yes At least one linked worktree or local branch (other than main) exists
Branch selection User input all or enter comma-separated numbers from the displayed list
Working tree clean Every worktree entry Dirty worktrees are reported in advance and skipped; branch-only entries always pass pre-check
Main branch name Automatic/Ask Detect from remote; ask the user when it cannot be determined
Network access Yes pull and push to origin requires network access

Output contract

Element Description
Merge commits Each successful branch produces one on <main-branch> produces one on --no-ff merge commit
Remote push Each successful branch is pushed once, updating origin/<main-branch>
Worktree removal All successful type: worktree entries are removed from git worktree list are removed from
Branch deletion Optional, executed after user confirmation; only git branch -d
Batch summary report Per-branch table: type / branch / merge / push / cleanup / branch deletion status

Constraints (Restrictions)

Hard Boundaries

  • Force push is prohibited(--force、--force-with-lease) to any branch
  • It is prohibited to remove the worktree after a merge or push failure
  • Automatic stash is prohibited uncommitted changes — report in advance and skip that worktree
  • Use of git branch -Dis prohibited — only -d(safe deletion)
  • It is prohibited to start any merge before the pre-check of all selected entries is complete
  • It is prohibited to continue executing inside a linked worktree or on a non-main branch of the main repository— stop and give the corresponding prompt

Skill Boundaries

  • Single worktree delivery: use inside the worktree deliver-feature
  • Commit pending changes: first use inside each worktree commit-work
  • rebase / squash: use directly before invoking this skill git rebase
  • Create PR: use platform-specific PR tools; this skill merges directly into main
  • Code review: use before committing review-diff; this skill does not perform code review

Anti-Patterns

Invocation context

✅ Run at the root of the main repository, on the main branch ❌ Do not run inside a linked worktree — that is the responsibility of deliver-feature ; after the worktree is deleted, the CWD becomes invalid, causing all subsequent commands to fail

Pre-check order

✅ Before starting any merge, perform a uniform dirty check on all selected worktree entries ❌ Do not check that entry only right before merging — a dirty worktree will be discovered only after some merges have already been committed

Merge method

✅ git merge --no-ff preserves branch history ❌ Do not use git merge --squash or fast-forward — history will be lost

Push safety

✅ Standard git push origin <main-branch> ❌ Never use on main --force or --force-with-lease

Cleanup order

✅ Remove the worktree only after both merge and push succeed ❌ Do not remove after merge but before push—if the push fails, the branch will be inaccessible

Branch deletion

✅ git branch -d(safe), and requires user confirmation ❌ Never use git branch -D(force)—may delete unmerged commits


Examples

Example 1: Mixed worktree branches and standalone branches (normal path)

Scenario: Two worktree branches and one standalone branch are ready to be merged into main。

Execution process:

# 步骤 3:扫描
git worktree list --porcelain
# main: /repos/myapp  +  /repos/myapp-auth feat/user-auth  +  /repos/myapp-api feat/api-v2

git branch --format='%(refname:short)'
# feat/user-auth(已在 worktree 中——去重)
# feat/api-v2   (已在 worktree 中——去重)
# feat/dashboard(独立分支)

# 展示列表:
#   [1]  worktree  /repos/myapp-auth  feat/user-auth  (last commit: 2 days ago)
#   [2]  worktree  /repos/myapp-api   feat/api-v2     (last commit: 5 days ago)
#   [3]  branch    —                  feat/dashboard  (last commit: 14 days ago — STALE)
# 用户选择:all

# 步骤 4:预检
git -C /repos/myapp-auth status --porcelain   # (empty ✓)
git -C /repos/myapp-api  status --porcelain   # (empty ✓)
# feat/dashboard — 无 worktree,跳过 ✓

# 步骤 5:顺序 merge + push(3 条)
git pull origin main
git merge --no-ff feat/user-auth -m "Merge branch 'feat/user-auth' into main"
git push origin main

git pull origin main
git merge --no-ff feat/api-v2 -m "Merge branch 'feat/api-v2' into main"
git push origin main

git pull origin main
git merge --no-ff feat/dashboard -m "Merge branch 'feat/dashboard' into main"
git push origin main

# 步骤 6:清理——仅 worktree 条目
pwd                                       # /repos/myapp ✓
git worktree remove /repos/myapp-auth
git worktree remove /repos/myapp-api
# feat/dashboard — type: branch,跳过

# 步骤 7:删除分支——用户选 all
git branch -d feat/user-auth
git branch -d feat/api-v2
git branch -d feat/dashboard

Summary:

integrate-branches summary
──────────────────────────────────────────────────────────────────────────
Type      Branch            Merge  Push  Cleanup  Branch-Del
worktree  feat/user-auth    ✓      ✓     ✓        deleted
worktree  feat/api-v2       ✓      ✓     ✓        deleted
branch    feat/dashboard    ✓      ✓     —        deleted
──────────────────────────────────────────────────────────────────────────
Main repo: /repos/myapp · Main branch: main · Remote: origin

Example 2: Dirty worktree skipped, standalone branch proceeds normally

Scenario: Three entries are selected, and one worktree has uncommitted changes.

Execution process:

# 步骤 4:预检
git -C /repos/myapp-auth  status --porcelain   # (empty ✓)
git -C /repos/myapp-api   status --porcelain   # M  src/api.ts  ← 脏
# feat/dashboard — 无 worktree,跳过 ✓

Skill reports:

Pre-flight check — dirty worktrees (will be skipped):
  /repos/myapp-api  (feat/api-v2)    — 1 uncommitted file(s)

User answers continue → feat/user-auth and feat/dashboard continue;feat/api-v2 skip.

Summary:

integrate-branches summary
──────────────────────────────────────────────────────────────────────────
Type      Branch            Merge          Push  Cleanup  Branch-Del
worktree  feat/user-auth    ✓              ✓     ✓        deleted
worktree  feat/api-v2       skipped(dirty) —     —        —
branch    feat/dashboard    ✓              ✓     —        deleted
──────────────────────────────────────────────────────────────────────────

Example 3: Wrong context—invoked inside a worktree

Scenario: The developer is on the /repos/myapp-api branch of feat/api-v2 .

Execution process:

git rev-parse --git-dir          # /repos/myapp/.git/worktrees/myapp-api
git rev-parse --git-common-dir   # /repos/myapp/.git   (不同 → linked worktree)

Skill stops:

"This skill must run at the root of the main repository, not inside a worktree. Current location:/repos/myapp-api. To deliver the branch of the current worktree, use deliver-feature。"


AI Refactor Instruction

If this skill produces incorrect behavior:

  1. Wrong context continues execution: Return to step 1, add the git-dir vs git-common-dir comparison and branch equality validation
  2. Precheck skipped or deferred: Return to step 4, ensure prechecks are completed for all selected entries before any merge
  3. Failed worktree deleted: Stop; only <succeeded-list> entries of type: worktree may be removed
  4. branch-only entry executed worktree remove: branch-only entries have no worktree path—skip step 6 entirely
  5. Attempted force push: Replace with a standard push; if it fails, stop and report
  6. Pull skipped before merge: Re-execute from the pull step
  7. Worktree branch appears duplicated: The deduplication in step 3 must exclude branches already in the worktree list from the git branch output

Self-Check

  • Invocation context verified:git rev-parse --git-dir equals git rev-parse --git-common-dir, and the current branch equals <main-branch>
  • Main branch confirmed: Automatically detected or explicitly provided by the user, with no assumptions made
  • Both sources scanned:git worktree list --porcelain and git branch have both been parsed, and non-main entries have been displayed
  • Deduplication executed: Branches in worktrees do not appear duplicated in the branch list
  • User selection recorded: Obtained before any precheck all or a subset of indices
  • Prechecks for all worktree entries completed before any merge: Executed for each selected worktree entry git -C <path> status --porcelain
  • branch-only entries skipped dirty check: They have no working tree to check
  • Dirty worktree is uniformly reported: all dirty entries are listed together before the continue/halt prompt
  • Pulled before every merge: before every git merge --no-ff was executed immediately before git pull origin <main-branch>
  • Used --no-ff merge: confirmed use of git merge --no-ff, no fast-forward or squash
  • Marked only after push succeeded succeeded: only after git push returned 0 is the entry added to <succeeded-list>
  • Uniform cleanup is performed only for successful worktree entries:git worktree remove was never called on failed, skipped, or type: branch entries
  • CWD confirmed before cleanup: before any git worktree remove before pwd equals <main-repo>
  • Branch deletion used -d: no -D flag in any branch deletion command; the user has confirmed each branch
  • Summary report has been output: the status code for each branch is correctly filled in
  • No force push used: no --force or --force-with-lease