Sync

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