GitHub Sync 🔄

Keep all your GitHub projects synchronized across multiple computers with one simple command!

Perfect for developers who work on multiple machines (home, work, laptop) and want to keep their projects effortlessly in sync.

🚀 Quick Start

Install & Run (Anyone can do this!)

# Option 1: Run directly (no installation needed)
npx github-sync

# Option 2: Install globally (recommended)
npm install -g github-sync
github-sync

That's it! The setup wizard will guide you through everything.

✨ What GitHub Sync Does

For Non-Developers: Think of it like Dropbox, but specifically for your coding projects. It keeps all your GitHub projects up-to-date across all your computers automatically.

For Developers: Automatically pulls the latest changes from all your GitHub repositories with smart conflict handling and beautiful CLI experience.

Key Features

• 🎯 One Command Sync - github-sync updates everything
• 🛡️ Safe by Default - Never overwrites uncommitted work
• 🎨 Beautiful Interface - Clean, minimal output with helpful icons
• ⚡ Smart Discovery - Automatically finds and clones your GitHub repos
• 🔧 Zero Config - Works out of the box with sensible defaults
• 🌐 Cross-Platform - Works on macOS, Linux, and Windows

📖 How It Works

The Magic Behind the Scenes

1. Discovers all Git repositories in your chosen folder
2. Checks each repository for updates from GitHub
3. Pulls new changes safely (only if no uncommitted work)
4. Skips repositories with unsaved changes (protecting your work)
5. Reports what was updated with clear status messages

Typical Daily Workflow

Morning at Work:

github-sync
# ✅ personal-website    
# ✅ work-project       (updated: 5 new commits)
# ⚠️  client-app        (uncommitted changes)

Evening at Home:

github-sync  
# ✅ work-project       (updated: 3 new commits)
# ✅ personal-website   
# ✅ hobby-game         (updated: 2 new commits)

🛠️ Commands

Basic Commands (Start Here!)

# Sync all your projects (most common command)
github-sync

# See what needs updating without changing anything
github-sync status

# Get your GitHub projects onto a new computer
github-sync clone

# Change your settings
github-sync setup

Advanced Options

# Clone all your repositories at once
github-sync clone --all

# Clone specific repositories
github-sync clone --select "1,3,5"
github-sync clone --select "1-10"

# Get help
github-sync --help

🏗️ Installation Methods

Method 1: Direct Run (Easiest)

npx github-sync

Perfect for trying it out or occasional use.

Method 2: Global Install (Recommended)

npm install -g github-sync
github-sync

Best for daily use - command available everywhere.

Method 3: Project-Specific

npm install github-sync
npx github-sync

Good for team setups or specific projects.

⚙️ Setup & Configuration

First Time Setup

When you run github-sync for the first time, it will ask you:

1. 📁 Where to store projects?

   • Default: ~/GitHub (recommended)
   • You can choose any folder you like

2. 🔐 GitHub Authentication (optional but recommended)

   • Allows cloning private repositories
   • Enables the clone command to discover all your repos
   • Uses GitHub CLI for secure authentication

3. ⚙️ How to handle uncommitted changes?

   • Skip (recommended): Safer, won't touch repos with unsaved work
   • Auto-stash: Advanced, automatically saves your work temporarily

Configuration File

Settings are saved in ~/.github-sync/config.json:

{
  "baseDir": "/Users/yourname/GitHub",
  "autoStash": false,
  "githubUser": "yourusername"
}

🔐 Authentication Setup

To use the clone command and access private repositories:

Install GitHub CLI

# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
sudo apt install gh  # Ubuntu/Debian

Login to GitHub

gh auth login

Follow the prompts to authenticate through your browser.

📁 Recommended Folder Structure

Keep all your GitHub projects in one main folder:

~/GitHub/
├── personal-website/
├── work-project/
├── learning-python/
├── cool-app-idea/
└── open-source-contributions/

🛡️ Safety Features

GitHub Sync is designed to never lose your work:

• ✅ Never force pushes or pulls
• ✅ Skips repositories with uncommitted changes
• ✅ Shows clear warnings before any action
• ✅ Only pulls, never pushes your code
• ✅ Works with any Git hosting (GitHub, GitLab, etc.)

🚨 Troubleshooting

Common Issues & Solutions

"Command not found: github-sync"

# Make sure Node.js is installed
node --version

# Reinstall globally
npm install -g github-sync

"No repositories found"

• Run github-sync clone to get your repositories
• Or manually clone: cd ~/GitHub && git clone [your-repo-url]

"Authentication failed"

# Install and login to GitHub CLI
brew install gh    # or appropriate installer for your OS
gh auth login

"Permission denied"

• Don't use sudo with GitHub Sync
• Make sure you own the repositories folder
• Check your Git credentials: git config --global user.name

Sync failures

• Check internet connection
• Ensure you're authenticated: gh auth status
• Look for uncommitted changes in the problematic repository

🎯 Who Should Use This?

Perfect For:

• Developers with multiple computers (work laptop, home desktop, etc.)
• Students learning to code across different machines
• Team leads who need to stay updated on multiple projects
• Open source contributors tracking many repositories
• Anyone who wants their coding projects always in sync

Not Needed If:

• You only use one computer
• You only work on one project at a time
• You prefer manual Git workflows

🔄 Migration & Backup

Moving from Manual Git Workflows

1. Collect all your existing Git projects into one folder
2. Run github-sync setup to configure the folder
3. Use github-sync daily instead of manual git pull commands

Backup Your Configuration

Your settings are stored in ~/.github-sync/ - back this up to restore settings on new machines.

🤝 Contributing

Found a bug or have a suggestion?

1. Check existing issues: GitHub Issues
2. Create a new issue with details about your problem or idea
3. Or submit a pull request!

📜 License

MIT License - Use freely in personal and commercial projects!

❤️ Made With

• Node.js - Runtime environment
• Commander.js - CLI framework
• Chalk - Terminal colors
• Inquirer - Interactive prompts
• Simple-git - Git operations
• Ora - Loading spinners

Made with ❤️ to simplify developer workflows

💡 Tip: Add github-sync to your daily routine - run it every morning when you start coding!