GitHub Sync

Bidirectional sync between GitHub repositories and local directories. Pull files from any GitHub repo folder to your local workspace, and push changes back via pull requests.

Features

Pull from GitHub: Download files from any GitHub repo directory to your local workspace
Push via PR: Push local changes back to GitHub through automated pull requests
Incremental sync: Only downloads changed files using SHA-based tracking
Conflict resolution: Side-by-side diff view when both local and remote files have changed
Flexible configuration: Sync multiple repos/paths with include/exclude glob patterns
No git required: Falls back to GitHub REST API when git is not installed
Secure auth: Uses VSCode's built-in GitHub authentication, with GITHUB_TOKEN fallback

Quick Start

Install the extension
Open a workspace folder
Run "GitHub Sync: Init Config" from the Command Palette (Cmd+Shift+P)
Edit .github-sync.json to configure your sync mappings
Run "GitHub Sync: Pull" to sync files

Configuration

Create a .github-sync.json file in your workspace root:

{
  "mappings": [
    {
      "name": "My Claude Skills",
      "repo": "username/my-skills-repo",
      "branch": "main",
      "sourcePath": "skills",
      "destPath": ".claude/skills",
      "include": ["**/*.md"],
      "exclude": ["**/drafts/**"]
    }
  ]
}

Mapping options

Field	Required	Description
`name`	✅	Human-readable name for this mapping
`repo`	✅	GitHub repo in `owner/repo` format
`branch`		Branch to sync from (default: repo's default branch)
`sourcePath`	✅	Path within the repo to sync from
`destPath`	✅	Local destination (relative to workspace root, or absolute)
`include`		Glob patterns to include (default: all files)
`exclude`		Glob patterns to exclude

Commands

Command	Description
`GitHub Sync: Pull`	Pull all configured mappings
`GitHub Sync: Pull (Select Mapping)`	Choose which mappings to pull
`GitHub Sync: Push`	Push local changes for all mappings
`GitHub Sync: Push (Select Mapping)`	Choose which mappings to push
`GitHub Sync: Init Config`	Create a starter `.github-sync.json`
`GitHub Sync: Show Output`	Open the extension's output channel

How it works

Pull

Reads your .github-sync.json configuration
Fetches the directory tree from GitHub via REST API
Compares remote file SHAs against the local lockfile (.github-sync.lock)
Downloads only changed files, writing them atomically
If both local and remote have changed, shows a conflict resolution dialog

Push

Detects locally modified files by comparing content hashes
Creates a temporary sparse git checkout (or uses REST API if git unavailable)
Pushes changes to a new branch
Creates a pull request with a summary of changes

Authentication

The extension uses VSCode's built-in GitHub authentication by default. When you run a sync command for the first time, VSCode will prompt you to sign in to GitHub.

Alternatively, set the GITHUB_TOKEN environment variable for headless/CI scenarios.

Settings

Setting	Default	Description
`github-sync.logLevel`	`info`	Log verbosity: `debug`, `info`, `warn`, `error`

Requirements

VSCode 1.85.0 or later
A GitHub account (for authentication)
Git (optional, for push via sparse checkout — REST API fallback available)

License

MIT

Skills Sync

patrickw1029