---
name: "worktree-sync"
description: "Rebase or merge the current worktree branch on top of the updated target branch"
short_desc: "Sync worktree with target branch updates"
version: "1.0.0"
tags: ["git", "worktree", "rebase", "sync"]
---

# Worktree Sync Skill

Synchronize the current worktree branch with the latest changes from the target branch (main/master) via rebase or merge.

## When to Use

- The target branch has advanced while you were working in a worktree
- Before merging back (`/worktree-merge`) to minimize conflicts
- Periodically during long-running worktree sessions to stay current
- When CI/CD requires your branch to be up-to-date with main

## Workflow

### Phase 1: Validation

1. **Verify worktree**: Check if the current directory is a worktree.

```bash
git rev-parse --git-dir
```

The output must contain `/worktrees/`. If not, this skill can still work on regular branches — note this to the user.

2. **Identify current branch**: `git branch --show-current`

3. **Resolve target branch**:
   - If an argument is provided, use it as the target branch
   - Otherwise, detect default: check `main`, then `master`
   - If neither exists, ask the user

4. **Clean working tree**: Run `git status --porcelain`. If uncommitted changes exist, stop and ask the user to commit or stash first.

5. **Record rollback point**:

```bash
git rev-parse HEAD
```

Save this hash — if anything goes wrong, the user can `git reset --hard <hash>` to return to the pre-sync state.

### Phase 2: Divergence Assessment

1. **Fetch latest**:

```bash
git fetch origin <target>
```

2. **Check divergence**:

```bash
# Commits on target that we don't have
git log HEAD..origin/<target> --oneline

# Commits on our branch that target doesn't have
git log origin/<target>..HEAD --oneline

# Numeric summary
git rev-list --left-right --count HEAD...origin/<target>
```

3. **If target has NOT advanced** (0 new commits):
   - Report "Already up to date with `origin/<target>`"
   - Stop — no action needed

4. **Overlap analysis**:

```bash
git diff HEAD...origin/<target> --stat
```

Identify files modified on both sides — these are potential conflict zones.

### Phase 3: Strategy Selection

Based on Phase 2 assessment, recommend a strategy:

| Condition | Strategy | Risk |
|-----------|----------|------|
| Few worktree commits, no overlapping files | `git rebase origin/<target>` | Low |
| Overlapping files exist but manageable | `git rebase origin/<target>` with conflict guidance | Medium |
| Large divergence, many overlapping files | `git merge origin/<target>` (creates merge commit) | Lower risk, noisier history |

Present the recommendation with rationale:
- Number of new commits on each side
- Which files overlap
- Recommended strategy and why

**Wait for user confirmation** before proceeding.

### Phase 4: Execution

#### Rebase Strategy

```bash
git rebase origin/<target>
```

#### Merge Strategy

```bash
git merge origin/<target>
```

- If clean (no conflicts): proceed to Phase 6
- If conflicts: proceed to Phase 5

### Phase 5: Conflict Resolution

1. **List conflicted files**:

```bash
git diff --name-only --diff-filter=U
```

2. **For each conflicted file**, show:
   - The conflict markers and surrounding context
   - What changed on each side (ours vs theirs)

3. **Present options** — do NOT auto-resolve:
   - "Show me each conflict so I can decide" (guided resolution)
   - "Accept theirs for all conflicts" (`git checkout --theirs .`)
   - "Accept ours for all conflicts" (`git checkout --ours .`)
   - "Abort" (`git rebase --abort` or `git merge --abort`)

4. **After resolution**:

```bash
# For rebase
git add <resolved-files>
git rebase --continue

# For merge
git add <resolved-files>
git commit
```

5. **Rebase may have multiple rounds** — if additional conflicts appear on subsequent commits, repeat this phase.

### Phase 6: Verification

1. **Branch state**: `git log --oneline -5`
2. **No uncommitted changes**: `git status --porcelain`
3. **Report to user**:
   - How many commits from target were incorporated
   - Current HEAD position (hash + message)
   - Files modified on both sides (potential semantic conflicts even if git resolved cleanly)
   - Rollback command: `git reset --hard <pre-sync-hash>`
4. **Recommend**: run tests/build to verify semantic correctness

## Safety Rules

- **Never force-push** or use destructive git operations without explicit user confirmation
- **Never skip pre-commit hooks** (`--no-verify`)
- **Never auto-resolve conflicts** — always present options and wait for user decision
- **Always record pre-sync HEAD** so user can rollback
- If anything unexpected happens, **stop and explain** rather than guessing
- Only fetch from remote, never push — pushing is `/worktree-merge`'s responsibility
