syncing-repos

Manages multiple sub-repos registered in local repos/repos.json (gitignored; bootstrap from repos/repos.json.example). All operations emit JSON so agents can parse results.

When to Use

• Cloning repos for the first time (init)
• Pulling latest changes across all repos (refresh)
• Creating feature branches across repos for an epic (branch create)
• Cleaning up merged branches (branch cleanup)
• Checking sync status of all repos (status)
• Rebasing stacked branches

CLI Usage

bun run repo <command> [options]

All commands accept --repo <name> to target a single repo, or operate on all repos by default.

Commands

init

Clone or pull all repos in repos.json.

bun run repo init              # Non-interactive, JSON output
bun run repo init --human      # Human-readable output with progress

status

Show sync status of all repos.

bun run repo status
# → { "repos": [{ "name": "my-api", "branch": "main", "ahead": 0, "behind": 2, "dirty": false }] }

refresh

Pull and rebase all repos on their default branch.

bun run repo refresh
bun run repo refresh --repo my-api

reset

Hard reset a repo to its remote HEAD. Discards all local changes.

bun run repo reset --repo my-api    # DESTRUCTIVE — confirm before use

branch create

Create a feature branch in one or all repos.

bun run repo branch create feat/T-42-my-feature
bun run repo branch create feat/T-42-my-feature --repo my-api

branch cleanup

Delete merged branches from one or all repos.

bun run repo branch cleanup
bun run repo branch cleanup --repo my-api --dry-run

stacked-rebase

Rebase a stack of branches sequentially.

bun run repo stacked-rebase feat/base feat/feature-a feat/feature-b

Output Format

All commands return:

{
  "ok": true,
  "command": "init",
  "repos": [
    {
      "name": "my-api",
      "ok": true,
      "action": "cloned",
      "path": "repos/my-api",
      "branch": "main"
    }
  ],
  "errors": []
}

On failure:

{
  "ok": false,
  "command": "refresh",
  "repos": [...],
  "errors": [{ "repo": "my-api", "message": "merge conflict in src/index.ts" }]
}

repos.json Schema

{
  "repos": [
    {
      "name": "my-api",
      "url": "https://github.com/org/my-api.git",
      "defaultBranch": "main"
    }
  ]
}