name: Sync description: Synchronize files and directories between local, remote, and cloud storage reliably. metadata: {"clawdbot":{"emoji":"🔄","requires":{"anyBins":["rsync","rclone"]},"os":["linux","darwin","win32"]}}

File Synchronization Rules

rsync Fundamentals

• Trailing slash matters: rsync src/ copies contents, rsync src copies the folder itself — this is the #1 cause of wrong directory structures
• Always use -avz baseline: archive mode preserves permissions/timestamps, verbose shows progress, compress speeds transfers
• Add --delete only when you want destination to mirror source exactly — without it, deleted source files remain on destination
• Use --dry-run before any destructive sync — shows what would change without modifying anything

Exclusions

• Create an exclude file instead of multiple --exclude flags: rsync -avz --exclude-from=.syncignore src/ dest/
• Standard excludes for code projects: .git/, node_modules/, __pycache__/, .venv/, *.pyc, .DS_Store, Thumbs.db
• Exclude patterns are relative to source root — /logs/ excludes only top-level logs, logs/ excludes logs/ anywhere

Cloud Storage (rclone)

• rclone sync deletes destination files not in source; rclone copy only adds — use copy when unsure
• Configure remotes interactively: rclone config — never hardcode cloud credentials in scripts
• Test with --dry-run first, then --progress for visual feedback during actual sync
• For S3-compatible storage, set --s3-chunk-size 64M for large files to avoid timeouts

Verification

• After critical syncs, verify with checksums: rsync -avzc uses checksums instead of size/time (slower but certain)
• For rclone, use rclone check source: dest: to compare without transferring
• Log sync operations to file for audit: rsync -avz src/ dest/ | tee sync.log

Bidirectional Sync

• rsync is one-way only — for true bidirectional sync, use unison: unison dir1 dir2
• Unison detects conflicts when both sides change — resolve manually or set prefer rules
• Cloud services like Dropbox/Syncthing handle bidirectional automatically — don't reinvent with rsync

Remote Sync

• For SSH remotes, use key-based auth: rsync -avz -e "ssh -i ~/.ssh/key" src/ user@host:dest/
• Specify non-standard SSH port: -e "ssh -p 2222"
• Use --partial --progress for large files over unreliable connections — allows resume on failure

Common Pitfalls

• Syncing to mounted drives that unmount silently creates a local folder with the mount name — verify mount before sync
• Running sync without --delete repeatedly causes destination to accumulate deleted files forever
• Time-based sync fails across machines with clock skew — use --checksum for accuracy or sync NTP first