git-sync

When to Invoke This Skill

• Before creating new worktrees (ensure latest main)
• Periodically to stay up to date with team changes
• After multiple PRs have been merged
• When starting a new batch of issue work

Purpose

Keeps the local main branch synchronized with the remote repository, ensuring all new worktrees are based on the latest code.

Standard Workflow

#### Synchronizing Main Branch

1. Verify Current Branch

```bash

git branch --show-current

```

If not on main, switch:

```bash

git checkout main

```

2. Check for Uncommitted Changes

```bash

git status --short

```

If uncommitted changes exist on main:

• WARN USER - main should typically be clean
• Options:

- Stash: git stash push -m "Temp stash before sync"

- Commit to feature branch

- Abort sync

3. Fetch Latest from Remote

```bash

git fetch origin

```

This updates remote-tracking branches without modifying working directory.

4. Check If Behind Remote

```bash

git rev-list --count HEAD..origin/main

```

If count > 0, local is behind remote.

5. Pull Changes

```bash

git pull origin main --ff-only

```

Using --ff-only ensures:

• No merge commits created
• Only fast-forward updates allowed
• Fails if local has diverged (needs manual resolution)

6. Verify Sync Success

```bash

# Should show "Your branch is up to date with 'origin/main'"

git status

# Verify latest commit matches remote

git log -1 --oneline

git log origin/main -1 --oneline

```

7. Report Status

```

✅ Main branch synchronized

• Fetched latest changes from origin
• Fast-forwarded to origin/main
• Current commit: abc1234 Fix session bug
• Branch is up to date

```

Error Handling

#### Diverged Branches (Local Commits on Main)

If git pull --ff-only fails:

```bash

# Check divergence

git log HEAD..origin/main --oneline # Remote commits

git log origin/main..HEAD --oneline # Local commits

```

Resolution Options:

1. No Local Commits (should be normal):

```bash

git reset --hard origin/main

```

1. Local Commits Exist (unexpected):

- STOP and WARN USER

- Main branch should not have local commits

- Ask user:

- Move commits to feature branch?

- Discard local commits?

- Manual resolution needed?

#### Merge Conflicts

Should not happen on main (main should be clean), but if it does:

• STOP and ALERT USER
• Main branch has been modified locally
• Needs manual intervention

#### Network Issues

```bash

git fetch origin

# If fails, check network

git remote -v

```

Report to user: "Unable to fetch from remote. Check network connection."

Pre-Sync Validation

Before syncing, verify:

1. No Active Worktrees on Main

```bash

git worktree list | grep "\[main\]"

```

If main is checked out in multiple places, this could cause issues.

2. Clean Working Directory

```bash

git status --short

```

Main should typically be clean.

3. Remote Is Reachable

```bash

git ls-remote origin main

```

Verifies remote connectivity.

Post-Sync Actions

After successful sync:

1. Verify Worktrees Still Valid

Existing worktrees are based on old main commits, which is fine. They'll be rebased or merged when creating PRs.

2. Report Summary

```bash

# Show what changed

git log --oneline --graph --decorate -10

# Count new commits

git rev-list --count @{1}..HEAD

```

3. Inform User

```

✅ Sync complete - 5 new commits pulled

• Latest: Fix authentication timeout
• Ready to create new worktrees based on current main

```

Best Practices

When to Sync:

• Beginning of work session
• Before spawning workers for new issues
• After being notified of merged PRs
• When explicitly requested

When NOT to Sync:

• While workers are running (doesn't affect them)
• During active development on main (shouldn't happen)
• When network is unavailable

Frequency:

• At least once per work session
• Before each new batch of issues
• After multiple PRs merged to main

Example 1: Simple sync (no changes)

```

Context: Local main is up to date

Actions:

1. git checkout main
2. git fetch origin
3. git pull origin main --ff-only
4. git status

Result: "Already up to date"

```

Example 2: Sync with new commits

```

Context: 3 PRs were merged since last sync

Actions:

1. git checkout main
2. git fetch origin
3. git rev-list --count HEAD..origin/main

→ Output: 3

1. git pull origin main --ff-only
2. git log --oneline -3

Result:

✅ Main branch synchronized

• Pulled 3 new commits
• Latest: Fix session timeout (abc1234)
• Ready for new issue work

```

Example 3: Sync from feature branch

```

Context: Currently on feature branch

Actions:

1. git branch --show-current

→ Output: feature/issue-123

1. git checkout main
2. git fetch origin
3. git pull origin main --ff-only
4. git checkout feature/issue-123

Result: Main updated, returned to feature branch

```

Example 4: Uncommitted changes on main (unexpected)

```

Context: Main has uncommitted changes (shouldn't happen)

Actions:

1. git checkout main
2. git status --short

→ Output: M src/config.py

1. WARN USER: "Uncommitted changes on main branch detected"
2. Ask user: "Options:

- Stash changes: git stash

- Discard changes: git restore .

- Abort sync"

1. Based on choice, proceed or abort

Result: User handles unexpected state

```

Example 5: Diverged main (local commits)

```

Context: Main has local commits (shouldn't happen)

Actions:

1. git checkout main
2. git fetch origin
3. git pull origin main --ff-only

→ Error: "fatal: Not possible to fast-forward"

1. git log origin/main..HEAD --oneline

→ Output: 2 local commits

1. ALERT USER: "Main branch has local commits"
2. Ask: "Options:

- Reset to origin/main (discard local)

- Move commits to feature branch

- Manual resolution"

1. Based on choice:

- Reset: git reset --hard origin/main

- Feature branch: git checkout -b recover/main-commits && git checkout main && git reset --hard origin/main

- Manual: Stop and let user handle

Result: Main synchronized, local commits preserved if requested

```

Example 6: Sync before spawning workers

```

Context: About to spawn workers for issues #123, #456, #789

Actions:

1. git checkout main
2. git fetch origin
3. git pull origin main --ff-only
4. git log -1 --oneline

→ Latest commit shown

1. Report: "Main synchronized - ready to spawn 3 workers"

Result: All workers will be based on latest main

```