worktree-sync

Development

Sync git worktrees with remote and main branch changes. Use to keep long-running feature branches up-to-date.

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/data/worktree-sync/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/worktree-sync, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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/main or git merge
Resolve conflicts - If conflicts occur, fix files and git rebase --continue
Verify - Check git log to 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-create skill for creating worktrees
worktree-strategy.md