github-files-sync

GitHub Files Sync

Simple file synchronization tool using GitHub as storage.

Features

• Sync scattered files across multiple machines
• Use GitHub as central storage
• Auto-watch and auto-push - Automatically push changes when files are saved
• Auto-start on boot - Start watching on system startup (macOS/Linux)
• Simple CLI interface
• No symbolic links - direct file copy
• Minimal dependencies (Node.js built-ins only)

Installation

npm install -g github-files-sync

Usage

Initialize

gfs init <github-repo-url>

Add files to sync

gfs add ~/.zshrc
gfs add ~/scripts/deploy.sh

Push files to GitHub

gfs push

Pull files from GitHub

gfs pull

Check status

gfs status

Auto-sync with file watching

Watch files and automatically push changes to GitHub:

# Start watching
gfs watch start

# Check watch status
gfs watch status

# Stop watching
gfs watch stop

Override file path on specific machine

If you need a different path for a file on a specific machine:

gfs override home__zshrc ~/my-custom-zshrc
gfs pull  # Sync file to new location

Note: Path overrides are stored locally and NOT synced to other machines.

Configuration

Configuration is stored in ~/.sync-config/config.json

{
  "repository": "[e-mail]:user/sync-storage.git",
  "baseDir": "~",
  "localMappings": {
    "home__zshrc": ".zshrc",
    "home_scripts_deploy_sh": "work/scripts/deploy.sh"
  }
}

Key Features:

• Files are stored using relative paths from baseDir (default: home directory)
• localMappings can override paths on a per-machine basis
• Configuration is local only and NOT synced to other machines
• This allows different machines to have different file locations for the same synced files

Example: On Machine A, scripts_deploy_sh → ~/scripts/deploy.sh, but on Machine B it could be → ~/work/scripts/deploy.sh

Repository Structure

sync-storage/
├── .sync-manifest.json
└── files/
    ├── home__zshrc
    └── home_scripts_deploy_sh

Manifest format (.sync-manifest.json):

{
  "files": [
    {
      "id": "home__zshrc",
      "relativePath": ".zshrc",
      "lastModified": "2025-11-10T10:00:00Z",
      "hash": "abc123..."
    }
  ]
}

Auto-start on Boot

Simple Method (Recommended)

Enable auto-start with a single command:

# Enable auto-start
gfs watch autostart enable

# Check status
gfs watch autostart status

# Disable auto-start
gfs watch autostart disable

This works on both macOS and Linux, and automatically handles all platform-specific setup.

Advanced: Manual Setup

Click to expand manual setup instructions

macOS (launchd)

• Copy the plist file to LaunchAgents:

# If installed via npm
cp /usr/local/lib/node_modules/github-files-sync/autostart/com.github-files-sync.watch.plist ~/Library/LaunchAgents/

# Or use this to find the installed location
cp "$(npm root -g)/github-files-sync/autostart/com.github-files-sync.watch.plist" ~/Library/LaunchAgents/

• Load the service:

launchctl load ~/Library/LaunchAgents/com.github-files-sync.watch.plist

• Start the service:

launchctl start com.github-files-sync.watch

To stop auto-start:

launchctl unload ~/Library/LaunchAgents/com.github-files-sync.watch.plist

Linux (systemd)

• Copy the service file:

mkdir -p ~/.config/systemd/user

# If installed via npm
cp /usr/local/lib/node_modules/github-files-sync/autostart/github-files-sync-watch.service ~/.config/systemd/user/

# Or use this to find the installed location
cp "$(npm root -g)/github-files-sync/autostart/github-files-sync-watch.service" ~/.config/systemd/user/

• Enable and start the service:

systemctl --user enable github-files-sync-watch.service
systemctl --user start github-files-sync-watch.service

• Check status:

systemctl --user status github-files-sync-watch.service

To stop auto-start:

systemctl --user stop github-files-sync-watch.service
systemctl --user disable github-files-sync-watch.service

License

MIT