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
• 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

macOS (launchd)

• Copy the plist file to LaunchAgents:

cp __docs__/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
cp __docs__/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