Git Sync

Instructions

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

git branch --show-current

If not on main, switch:

git checkout main

2. Check for Uncommitted Changes

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

git fetch origin

This updates remote-tracking branches without modifying working directory.

4. Check If Behind Remote

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

If count > 0, local is behind remote.

5. Pull Changes

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

# 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:

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

Resolution Options:

No Local Commits (should be normal):
```
git reset --hard origin/main
```
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

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

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

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

2. Clean Working Directory

git status --short

Main should typically be clean.

3. Remote Is Reachable

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

# 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

Examples

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
4. git pull origin main --ff-only
5. 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
2. git checkout main
3. git fetch origin
4. git pull origin main --ff-only
5. 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
3. WARN USER: "Uncommitted changes on main branch detected"
4. Ask user: "Options:
   - Stash changes: git stash
   - Discard changes: git restore .
   - Abort sync"
5. 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"
4. git log origin/main..HEAD --oneline
   → Output: 2 local commits
5. ALERT USER: "Main branch has local commits"
6. Ask: "Options:
   - Reset to origin/main (discard local)
   - Move commits to feature branch
   - Manual resolution"
7. 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
5. Report: "Main synchronized - ready to spawn 3 workers"

Result: All workers will be based on latest main

git-sync