home / skills / sounder25 / google-antigravity-skills-library / 03_sync_repos

03_sync_repos skill

safe

This skill detects drift across multiple git repositories, reports ahead/behind status, and optionally applies safe sync actions.

npx playbooks add skill sounder25/google-antigravity-skills-library --skill 03_sync_repos

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.6 KB

---
name: Sync Multi-Repo State
description: Detects drift between multiple git repositories (e.g. forks, mirrors, or multi-module projects). Generates a drift report and optionally applies sync actions.
version: 1.0.0
author: Antigravity Skills Library
created: 2026-01-15
leverage_score: 4/5
---

# SKILL-003: Sync Multi-Repo State

## Overview

When working with split repositories (e.g., `Scrutor` and `Scrutor Test` having copies of `execution-specs`), state drift is a major risk. This skill analyzes multiple repos to report on ahead/behind commits, uncommitted changes, and branch divergence.

## Trigger Phrases

- `sync repos`
- `check repo drift`
- `compare repos`
- `multi-repo status`

## Inputs

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--repos` | string[] | No | Auto-detect | List of repo paths to compare |
| `--reference` | string | No | First repo | The "source of truth" repo path |
| `--apply` | switch | No | False | **Unsafe:** Attempt to fast-forward/merge |

## Outputs

1. **Console Report:** Matrix of repo status.
2. **Markdown Report:** `REPO_SYNC_REPORT.md`.

## Preconditions

1. All targets must be valid git repositories.

## Safety/QA Checks

1. **Read-Only Default:** By default, only reports status.
2. **Safety Check:** `--apply` requires clean status in target repos.
3. **Backup:** `--apply` creates backup branch before merging.

## Implementation

See `sync_repos.ps1`.

## Integration

```powershell
.\skills\03_sync_repos\sync_repos.ps1 -Repos "C:\projects\Scrutor\execution-specs", "C:\projects\Scrutor Test\execution-specs"
```

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.

FAQ

What happens if --apply is run on repos with uncommitted changes?

The safety checks block automatic sync; --apply requires clean working trees and will abort if targets have uncommitted changes.

Does the skill overwrite anything without a backup?

No. When --apply is used the script creates a backup branch before attempting any merge or fast-forward.

Can I compare repos without specifying paths?

Yes. If --repos is omitted the tool attempts to auto-detect candidate repositories in the current context.