syncing-branch

cblecker 的头像作者 cblecker

所有同步操作的标准工作流程("同步分支"、"拉取最新"、"获取最新更改"、"与上游同步"):替换基于bash的git获取/拉取/合并工作流程—检测fork与origin,从正确的远程获取,安全合并并带有快速前进检查。git工作流的规范分支同步实现。

📖 中文导读:所有同步操作的标准工作流程("同步分支"、"拉取最新"、"获取最新更改"、"与上游同步"):替换基于bash的git获取/拉取/合并工作流程—检测fork与origin,从正确的远程获取,安全合并并带有快速前进检查。git工作流的规范分支同步实现。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: Sync a git branch description: Provides fork-aware branch synchronization with automatic remote detection and safe merge handling. Detects fork vs origin repositories, fetches from correct remotes (upstream for forks), and handles fast-forward merges with conflict prevention. Use for 'sync branch', 'pull latest', 'get latest changes', 'sync with upstream', 'update from main'. model: haiku

Skill: Syncing a Branch

When to Use This Skill

Use this skill for sync requests: "sync my branch", "pull latest", "sync with remote", "update my branch", "get latest from origin/upstream".

Use other skills for: rebasing (rebasing-branch), creating PRs (creating-pull-request), viewing remotes (git commands).

Workflow Description

Updates branch with remote changes, auto-detecting fork vs origin scenarios.

Extract from user request: target branch (if specified, else current)


Phase 1: Branch Identification and Checkout

Objective: Determine which branch to sync and switch to it if needed.

Steps:

  1. Determine target branch from user request:

    • Check for specific branch (e.g., "sync main", "sync the develop branch")
    • IF branch specified: use specified branch
    • IF not specified: get current branch to use as default
  2. Checkout target branch if specified and different from current:

    git checkout <target-branch>
    

Validation Gate: IF checkout fails:

  • Analyze error:
    • "error: pathspec '...' did not match": Branch doesn't exist
    • "error: Your local changes": Dirty working tree (will be caught by Phase 2)
    • Other: Permission issues
  • Explain error
  • Propose solution:
    • Doesn't exist: "Create branch first or verify name"
    • Permission: "Check repository access"
  • Wait for user to resolve

Continue to Phase 2.


Phase 2: Execute Sync (Optimized)

Objective: Perform fork-aware branch synchronization in a single atomic operation.

Plan Mode: Auto-enforced read-only if active

Steps:

  1. Run ${CLAUDE_PLUGIN_ROOT}/scripts/sync-branch.sh (optionally pass target-branch parameter if user specified a branch in Phase 1, otherwise omit to sync current branch)

  2. Parse the JSON response and handle results:

IF success: false:

See reference/error-types.md for detailed error type handling.

Read reference/error-types.md and match error_type from response to documented handling. Follow the prescribed action for the specific error type.

IF success: true:

Extract sync results:

{
  "success": true,
  "branch": "main",
  "is_fork": true,
  "operations_performed": [
    "fetched_all",
    "rebased_on_upstream",
    "pushed_to_origin"
  ],
  "commits_pulled": 3,
  "status": "up_to_date"
}

Continue to Phase 3.


Phase 3: Report Results

Objective: Confirm sync completed successfully with standardized output.

Steps:

  1. Format status message based on sync results:

    • Use branch, commits_pulled, and status from Phase 2 response
    • Determine repository type from is_fork flag
    • List operations from operations_performed array
  2. Report using standardized template:

    ✓ Branch Synced Successfully
    
    **Branch:** <branch> \
    **Repository Type:** <Fork|Origin-only> \
    **Commits Pulled:** <commits_pulled> \
    **Status:** <status description> \
    **Operations:** <operations_performed as list>
    

    Status descriptions:

    • up_to_date: "Branch is in sync with remote"
    • no_upstream: "No upstream tracking branch configured"
    • upstream_missing_branch: "Upstream doesn't have this branch"
    • push_failed: "Rebased on upstream but push to origin failed"
    • sync_conflict: "Encountered conflicts during sync"

Workflow complete.