ghsync

Files (2)

• SKILL.md
• ghsync.sh · scripts/

SKILL.md (first lines)

# ghsync: mirror and sync every repo you can access

Onboarding into a new enterprise means finding and cloning dozens of repos by
hand, then drifting out of date. This skill does both halves: it **discovers**
everything you can reach and **keeps it in sync**.

- **First run** — clones every accessible repo into a worktree-friendly layout.
- **Every run after** — fast-forward updates repos already on their default
  branch, updates their worktrees, and clones anything new. It never clobbers
  local work: repos with uncommitted changes or on a non-default branch are
  fetched but not pulled, and reported in the summary.

It is **org-agnostic** — point it at any GitHub org, GitHub Enterprise host, or
**personal account**. The script detects the account type itself: for an
organization it unions the teams you belong to with the org's repo list (so
direct-collaborator and public repos are included even with no team
membership); for a personal account it uses the account's repo list (private
repos included when it's your own account).

## How to run it

The script lives next to this file. Claude Code writes this skill's directory
into the script paths below when it loads the skill, so each path is already
absolute:

```bash
# Org is derived from the directory you run in. To mirror the "meridianhub"
# org, run from a directory named meridianhub:
cd ~/dev/github.com/meridianhub
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh"
```

The org defaults to the **basename of the directory you launch from**. So
running inside `~/dev/github.com/meridianhub` syncs the `meridianhub` org into
that directory. Override the org name or target directory explicitly when they
differ:

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/ghsync.sh" --org meridianhub --root ~/dev/github.com/meridianhub
```

## What to do when invoked

1. **Confirm the target.** Run with `--list-repos` first (or `--list-teams`
   for an org) so the user sees which account and how many repos before any
   cloning. This doubles as a check that the derived account name is correct.
2. **Dry run on first use against a new org** (`--dry-run`) to preview clones
   and updates without touching disk.
3. **Run the real sync.** Stream the output; the run ends with a summary
   (up-to-date / updated / failed / uncommitted / branch issues / worktrees).
4. **Surface the exceptions.** Call out anything under *Failed*, *Uncommitted
   changes*, or *Not on default branch* — these are the repos the user may need
   to deal with manually.

## Flags

| Flag | Effect |
|------|--------|
| `--org NAME` | Org or personal account to sync (default: basename of `--root` / cwd) |
| `--root DIR` | Directory to clone into (default: current directory) |
| `--list-teams` | List your teams in the org (with repo counts) and exit; orgs only |
| `--list-repos` | List the deduplicated accessible repos and exit |
| `--porcelain` | Machine-readable repo list: one name per line to stdout, all chatter to stderr; implies `--list-repos`. Consumed by downstream tooling such as `/ghreport`. |
| `--dry-run` | Show what would be cloned/updated without making changes |
| `--limit N` | Process only the first N repos (useful for a quick test) |
| `--quiet` | Suppress per-repository chatter; keep the final summary |

## Layout produced

```
<root>/<repo>/
  ├── <repo>-main/   # default-branch checkout, kept clean and up to date
  └── worktree/      # ready for `git worktree add ...`
```

This matches the worktree convention the rest of the toolkit assumes:
`<repo>-main` stays on the default branch and clean, and feature work happens in
sibling worktrees.

## Sync safety rules

- Repos with **uncommitted changes** are fetched but not pulled (reported under
  *Uncommitted changes*).
- Repos **not on their default branch** are fetched but not pulled (reported
  under *Not on default branch*).
- Updates are **fast-forward only** (`git pull --ff-only`) — no merge commits,
  no rebases, never a force.
- Worktrees on the default branch with no local changes are fast-forwarded too.
- A repo that exists locally without the `<repo>-main` structure is flagged
  (*Wrong structure*) rather than touched.

## Requirements & configuration

- **`gh` and `jq`** on `PATH`, and `gh auth status` must be authenticated. The
  script checks both up front.
- **GitHub Enterprise:** `gh` uses its configured host. Target a GHE instance by
  setting `GH_HOST=github.example.com` or running
  `gh auth login --hostname github.example.com` first.
- **Access model:** for an **organization**, repos are discovered by unioning
  two sources and deduplicating: the **teams you belong to** (`gh api
  user/teams`) and the **org repo list** (`gh repo list <org>`), which also
  surfaces public repos and repos reachable via direct collaborator grants
  outside any team. Team membership is **not** a precondition — a user on no
  team still syncs every repo they can otherwise access. For a **personal
  account**, repos come from `gh repo list <account>` (includes private repos
  when authenticated as that account). Empty repos with no default branch are
  skipped in both cases.
- **Blacklist:** export `GHSYNC_BLACKLIST="repo-a repo-b"` to skip oversized or
  problematic repos.
- **`timeout`:** optional but recommended (`brew install coreutils`) — caps each
  repo at 5 minutes so one hung clone can't stall the run.
- **Archived repos** are skipped from cloning and cached to
  `<root>/.gh_archived_repos` for reference.

From bjcoombs/ai-native-toolkit, Apache-2.0.

More from bjcoombs/ai-native-toolkit