mtc-project-sync-script/README.md

MTC Project Sync Script

A simple toolkit for synchronizing projects between remote servers and local development environments.

Setup

1. Clone the Repository

cd ~/Documents/GitHub
git clone <repository-url> mtc-project-sync-script

2. Create a Symlink in Your Projects Directory

Navigate to where you keep all your projects and create a symbolic link to the sync script:

cd ~/Documents/Projects  # or wherever you keep your projects
ln -s ~/Documents/GitHub/mtc-project-sync-script/sync-project.sh sync-project.sh

Why symlink? The script uses its own location to find the scripts/ folder and lazygit binary. A symlink preserves the connection to the original script location, so it can access these resources. This way, you only need one copy of the toolkit that all your projects can use.

3. Run the Sync Script

From your projects directory, run:

./sync-project.sh

Available flags:

./sync-project.sh -h            # Show help manual
./sync-project.sh --files-only  # Quick sync (files only, no scripts)
./sync-project.sh --sftp-only   # SFTP setup (no lazygit, no .gitignore updates)

What the Script Does

When you run sync-project.sh, it will:

1. Ask for configuration:

   • Server user@host (e.g., user@example.com)
   • SSH password
   • Server project path (defaults to ~/public_leo, supports ~ paths)
   • Local folder path (e.g., my-project)

2. Prepare the connection:

   • Auto-accepts new server host keys (first-time connections work seamlessly)
   • Resolves ~ paths to full paths via SSH
   • Syncs terminal info for ghostty/kitty terminals (full sync only)

3. Sync your project:

   • Creates a tar archive on the remote server
   • Downloads and extracts it to your local folder
   • Cleans up temporary files

4. Generate configuration and scripts:

   • Creates .vscode/sftp.json for VS Code SFTP extension
   • Generates helper scripts with your credentials pre-configured
   • Adds scripts to .gitignore (unless using --sftp-only)
   • Uploads lazygit to server (unless using --sftp-only)

Generated Scripts

After running the sync script, you'll have these helper scripts in your project:

remote-local.sh

Purpose: Download files from server to local machine

What it does:

• Uses rsync to pull files from remote server
• Only downloads changed files
• Excludes common development folders (node_modules, vendor, .git, etc.)

Use cases:

• Get latest changes from server
• Pull production data for debugging
• Sync before starting work

local-remote.sh

Purpose: Upload files from local machine to server

What it does:

• Uses rsync to push files to remote server
• Only uploads changed files
• Deletes remote files that don't exist locally
• Excludes common development folders

Use cases:

• Deploy local changes to server
• Push code updates
• Restore server from local backup

ssh.sh

Purpose: SSH into the remote server

What it does:

• Opens an SSH connection to your server
• Changes directory to your project path
• Multiple operation modes via flags

Usage:

./ssh.sh           # Normal SSH connection
./ssh.sh --db      # SSH with MySQL port forwarding (local:3306 -> remote:3306)
./ssh.sh --git     # Launch lazygit on server, sync changes back when done
./ssh.sh --todo    # Search for TODO markers in project files

Use cases:

• Run commands on the server
• Check logs
• Access remote database via localhost:3306
• Git operations via lazygit

sftp-watch.sh

Purpose: Continuous bidirectional sync

What it does:

• First runs remote-local.sh to sync down
• Watches for local file changes
• Automatically runs local-remote.sh when files change

Requirements: Needs watchexec installed (brew install watchexec)

Use cases:

• Development with live server testing
• Real-time sync during coding

watch-build.sh

Purpose: Watch for changes, build, and upload

What it does:

• Monitors files for changes
• Runs npm run build when changes detected
• Uploads built assets to server using local-remote.sh

Requirements:

• watchexec installed
• package.json with build script
• Node.js/npm installed

Use cases:

• Frontend development with build steps (React, Vue, etc.)
• Automatic deployment of compiled assets
• Continuous integration during development

Sync Modes

Default Mode

Full setup with all features:

• Syncs terminal info (xterm-ghostty or xterm-kitty)
• Downloads all project files
• Creates .vscode/sftp.json
• Generates all helper scripts
• Uploads lazygit to server
• Updates .gitignore

--files-only Mode

Quick sync for when you just need the files:

• Downloads project files (excludes node_modules, vendor)
• No helper scripts generated
• No configuration files created
• No lazygit upload

--sftp-only Mode

Lightweight setup for SFTP workflows:

• Downloads all project files
• Creates .vscode/sftp.json
• Generates: local-remote.sh, remote-local.sh, sftp-watch.sh, ssh.sh
• No lazygit upload
• No .gitignore modifications

Requirements

• bash - Shell scripting
• ssh/scp - Remote server access
• sshpass - Password authentication
• tar - Archive creation
• rsync - File synchronization
• watchexec (optional) - For watch mode scripts

Install on macOS:

brew install sshpass rsync watchexec

Install on Ubuntu/Debian:

sudo apt-get install sshpass rsync openssh-client