03_sync_repos_skill

Overview

This skill detects and reports state drift across multiple Git repositories such as forks, mirrors, or split multi-module projects. It produces a clear matrix of ahead/behind commits, uncommitted changes, and branch divergence, and can optionally apply safe sync actions when explicitly allowed. The default behavior is read-only to avoid accidental data loss.

How this skill works

The script scans each provided repo (or auto-detects candidates) and compares their branches and commit histories against a reference repo. It summarizes ahead/behind counts, uncommitted working tree changes, and branch divergence in both a console matrix and a Markdown report (REPO_SYNC_REPORT.md). When the --apply flag is used, it enforces safety gates: it requires clean working trees, creates backup branches, and attempts controlled fast-forwards or merges.

When to use it

• Before releasing or merging cross-repo changes to ensure consistent state.
• When maintaining mirrors or forks to detect and reconcile drift.
• In multi-module projects where modules live in separate repos and must stay aligned.
• During CI audits to generate an actionable sync report for reviewers.
• Prior to automated deployments to avoid unexpected divergence.

Best practices

• Run in default read-only mode to evaluate drift before any automatic fix.
• Specify an explicit --reference repo to set a clear source of truth.
• Require clean working trees on target repos before enabling --apply.
• Review the generated REPO_SYNC_REPORT.md and backups before accepting changes.
• Integrate into CI pipelines as a pre-merge or pre-deploy check.

Example use cases

• Compare a main repository and its test repo copy to find missing commits or local edits.
• Audit multiple forks of a library to identify which forks are ahead or behind upstream.
• Automatically generate a drift report for maintainers before a release.
• Safely fast-forward a downstream repo to match the reference after manual approval.
• Detect uncommitted developer changes that would block automated sync operations.