worktree-sync
Sync git worktrees with remote and main branch changes. Use to keep long-running feature branches up-to-date.
When & Why to Use This Skill
The Worktree Sync skill streamlines Git workflows by automating the synchronization of multiple worktrees with remote repositories and the main branch. It helps developers maintain code consistency, minimize merge conflicts, and ensure that long-running feature branches stay up-to-date with the latest upstream changes through structured rebase or merge processes.
Use Cases
- Maintaining long-running feature branches by regularly pulling and integrating the latest changes from the main branch to prevent significant code divergence.
- Synchronizing local environments before creating or updating Pull Requests to ensure a clean, conflict-free merge into the primary codebase.
- Managing complex multi-tasking setups where developers need to keep various project versions updated across different worktrees simultaneously.
- Streamlining the conflict resolution process by providing a standardized workflow for fetching, rebasing, and verifying branch integrity.
| name | worktree-sync |
|---|---|
| description | "Sync git worktrees with remote and main branch changes. Use to keep long-running feature branches up-to-date." |
| mcp_fallback | none |
| category | worktree |
Worktree Sync
Keep worktrees synchronized with remote changes.
When to Use
- Long-running feature branches
- Main branch has new commits
- Before creating/updating PR
- Resolving merge conflicts
- Feature branch is diverged from main
Quick Reference
# Fetch latest from remote (works in any worktree)
git fetch origin
# Update main worktree
cd ../ProjectOdyssey && git pull origin main
# Update feature worktree (rebase approach)
cd ../ProjectOdyssey-42-feature && git rebase origin/main
# Update feature worktree (merge approach)
cd ../ProjectOdyssey-42-feature && git merge origin/main
# Auto-sync all worktrees
./scripts/sync_all_worktrees.sh
Workflow
- Fetch remote -
git fetch origin(any worktree) - Update main - Navigate to main worktree,
git pull origin main - Update feature - Navigate to feature worktree,
git rebase origin/mainorgit merge - Resolve conflicts - If conflicts occur, fix files and
git rebase --continue - Verify - Check
git logto confirm main branch changes are included
Rebase vs Merge
| Approach | Use When | Command |
|---|---|---|
| Rebase | Linear history preferred | git rebase origin/main |
| Merge | Preserving branch history | git merge origin/main |
Error Handling
| Error | Solution |
|---|---|
| Conflicts during rebase | Run git status, fix files, git add ., git rebase --continue |
| Diverged branches | Use git pull --rebase origin main |
| Uncommitted changes | Commit or stash before syncing |
| Detached HEAD | Check git status and git checkout <branch> |
Conflict Resolution
# If conflicts occur
git status # See conflicted files
# Edit files to resolve conflicts
# Then continue
git add .
git rebase --continue
# Or abort if something went wrong
git rebase --abort
Best Practices
- Fetch regularly to catch conflicts early
- Sync before creating PR to avoid merge conflicts
- Keep feature branches short-lived (2-3 days max)
- Resolve conflicts immediately
- Use rebase for linear history (preferred for this project)
References
- See
worktree-createskill for creating worktrees - worktree-strategy.md