github-sync

Sync the current git repository or local child git repositories to same-name GitHub repositories, and batch delete remote repositories by gh repo list filters.

cd /path/to/parent-folder
npx github-sync

cd /path/to/single-repo
npx github-sync

npx github-sync delete-remote --fork --language JavaScript

npx github-sync delete-remote --fork --language JavaScript --dry-run

Options

github-sync [--include NAME] [--exclude NAME]
github-sync delete-remote [--fork] [--language LANGUAGE] [--include NAME] [--exclude NAME] [--dry-run] [--yes]

• -i, --include NAME: only sync a direct child directory by name. Repeatable.
• -e, --exclude NAME: skip a direct child directory by name. Repeatable.
• delete-remote --fork: delete only fork repositories owned by the target owner.
• delete-remote -l, --language LANGUAGE: delete only repositories whose primary language matches LANGUAGE.
• delete-remote -i, --include NAME: only delete a repository by name. Repeatable.
• delete-remote -e, --exclude NAME: skip a repository by name. Repeatable.
• delete-remote --dry-run: print matched repositories without deleting them.
• delete-remote --yes: pass --yes to each gh repo delete call.

delete-remote requires at least one filter, either --fork or --language, so an unfiltered owner-wide delete cannot run by accident.

Sync --include and --exclude apply only in child-repository mode. If the current directory is itself an independent git repository, github-sync syncs the current repository. In delete-remote mode, --include and --exclude filter matched remote repositories by repository name.

Why Not Plain gh?

gh already provides the primitives: gh repo list can filter repositories, and gh repo delete can delete one repository. github-sync combines those steps into a safer batch workflow:

1. Uses gh repo list with the supported filters, currently --fork and --language.
2. Supports repeated --include and --exclude name filters on top of the gh repo list result.
3. Prints the exact matched repository list before deletion starts.
4. Supports --dry-run to audit the matched list without deleting anything.
5. Deletes every matched repository by calling gh repo delete for each one.
6. Refuses to run remote deletion without a filter.
7. Uses the active gh account as the GitHub owner for sync and cleanup.

This is useful when cleaning generated forks, experiments, or language-specific scratch repositories where deleting one repo at a time through gh is tedious.

For syncing, github-sync also wraps the common local workflow around gh:

1. Uses gh repo create --source --remote when a matching GitHub repository does not exist yet.
2. Uses gh repo view --json url to resolve the HTTPS remote URL instead of constructing GitHub URLs manually or using SSH.
3. Uses gh repo sync for remote-to-local fast-forwards when branch names match.
4. Keeps git only for local repository operations that gh repo does not replace: checking the worktree, committing local changes, comparing branch ancestry, pushing local commits, and applying local fast-forwards.

Behavior

When the current directory is an independent git repository, github-sync:

1. Commits local changes so the worktree is clean.
2. Ensures a same-name GitHub repository exists.
3. Adds or updates the configured remote for the current repository.
4. Syncs local and remote when one side can fast-forward the other.
5. Skips syncing if local and remote histories diverge.

When the current directory is not an independent git repository, github-sync checks each direct child directory:

1. Skips the child if it is not an independent git repository.
2. Commits local changes so the worktree is clean.
3. Ensures a same-name GitHub repository exists.
4. Uses gh repo sync for remote-to-local fast-forwards when local and remote branch names match.
5. Falls back to git for branch creation, local-to-remote pushes, branch-name mismatches, or when gh repo sync cannot complete the sync.
6. Skips that child directory if local and remote histories diverge.

Prerequisites: git, gh, find, realpath, and sort.