dris1153 Upstream Sync
Sync forked/cloned open source repos with latest upstream changes. Instead of merging commits directly, this skill extracts upstream diffs, evaluates each change, and applies them by editing files directly.
When to Use
- User mentions "sync", "upstream", "fork", "merge upstream", "rebase upstream"
- User wants to review new commits from an original open source repo
- User needs to integrate upstream changes into their customized branch
- User asks about conflicts between their changes and upstream
Core Principle
Never merge/rebase/cherry-pick commits from upstream. Instead:
- Extract the actual diffs from upstream
- Read and evaluate each change against the local project
- Apply relevant changes by editing files directly (Edit/Write tools)
This gives full control over what gets applied and how, preserving the project's own commit history.
Workflow
Read references/sync-workflow.md for the full step-by-step process.
1. Check Upstream Status
Run scripts/upstream-status.js to detect upstream remote, fetch latest, and list new commits:
node <skill-path>/scripts/upstream-status.js [--remote <name>] [--branch <branch>] [--since <date>] [--format json|text]
2. Extract Upstream Diffs
Run scripts/upstream-diff.js to get per-file diffs from upstream since last sync:
# All changes since last sync
node <skill-path>/scripts/upstream-diff.js [--remote <name>] [--branch <branch>] [--format json|text]
# Specific file only
node <skill-path>/scripts/upstream-diff.js --file <path> [--format json]
# Specific commit only
node <skill-path>/scripts/upstream-diff.js --commit <hash> [--format json]
# List changed files without diffs
node <skill-path>/scripts/upstream-diff.js --files-only
3. Evaluate & Apply
For each changed file from upstream:
- Read the upstream diff to understand what changed and why
- Read the current local version of the file
- Evaluate: should this change be applied? adapted? skipped?
- If applying: edit the file directly using Edit/Write tools
- If adapting: modify the upstream change to fit local customizations
Read references/review-guide.md for evaluation methodology.
4. Overlap Detection (Optional)
Run scripts/conflict-preview.js to identify files modified on both sides:
node <skill-path>/scripts/conflict-preview.js [--remote <name>] [--branch <branch>] [--format json|text]
This helps prioritize which files need careful evaluation.
5. Save Sync State
After applying changes, save the sync point so the next sync starts from here:
node <skill-path>/scripts/sync-state.js save [--remote <name>] [--branch <branch>]
Commit .upstream-sync.json to persist the sync point across machines.
To check current state or reset:
node <skill-path>/scripts/sync-state.js show
node <skill-path>/scripts/sync-state.js reset
6. Verify & Report
- Run existing test suite
- Build the project
- Review changes with
git diff - Report to user: Present a summary of all changes applied. See format below.
Sync Report Format
After completing the sync, ALWAYS present a clear summary to the user:
## Upstream Sync Report
**Source**: upstream/main (commits <first-hash>...<last-hash>)
**Date range**: <oldest-commit-date> → <newest-commit-date>
**Total upstream commits reviewed**: <n>
### Applied Changes
- **<file-path>**: <brief description of what was updated and why>
- **<file-path>**: <brief description>
...
### New Files Added
- **<file-path>**: <what this file does>
### Skipped Changes
- **<file-path>**: <reason for skipping> (e.g., conflicts with local customization, irrelevant feature)
### Deleted Files
- **<file-path>**: <reason for deletion>
### Notes
- <any important context, breaking changes, or follow-up actions needed>
This report helps the user understand exactly what changed and why, so they can make informed decisions about testing and deployment.
Script Options
All scripts support --format json for structured output.
Environment variables (.env):
UPSTREAM_URL- URL of the original repo (auto-creates remote if needed)UPSTREAM_REMOTE- Default upstream remote name (default:upstream)UPSTREAM_BRANCH- Default upstream branch (default:main)