Backup and sync

Recommended options

• Git — multi-device + full history + best for teams
• iCloud / OneDrive — simplest for solo multi-device
• Dropbox / Syncthing — cross-platform, no cloud at all (Syncthing)
• Cold backup: rclone to S3 / B2 / R2 object storage
• Time Machine / File History — the foundation under any of the above

Git sync, in practice

Git is the strongest companion for a writing vault — full history, diffable, blameable, branchable. Make the vault a git repo, use the .gitignore recommended in secure-api-key, and push to a private GitHub repo or a self-hosted Gitea / Gogs.

A common cadence: git add -p after a writing session, commit, push once a day. You get atomic history without the remote slowing you down.

• Always ignore .kition/secrets/ and .kition/cache/
• Close the vault before committing — keeps index and lock files out of your diff
• Large attachments (video, PDF): use Git LFS or skip Git entirely
• When collaborating: branch + PR; table-schema conflicts are the main thing to hand-merge

# Inside the vault folder
git init
git remote add origin [email protected]:you/my-vault.git

# Track everything except the .gitignore entries above
git add .gitignore Notes Projects Tables Resources
git commit -m "Initial vault"
git push -u origin main

Cloud sync — pick one

iCloud Drive / OneDrive / Dropbox can keep the vault in sync across machines. They all sync at the folder level, which works perfectly for markdown and .kitable files. The catch is the index in .kition/ — it is a hot file, so syncing it ships invalid deltas 99% of the time.

The workaround: let the cloud sync the whole vault but exclude .kition/index/ and .kition/cache/. The index rebuilds automatically per device.

• iCloud Drive: turn off Optimize Mac Storage so files are not evicted
• OneDrive: mark the vault directory as Always keep on this device
• Dropbox: Selective Sync to exclude .kition/index/
• Syncthing: fully local, no third party, but you manage the ports

Cold backup with rclone

Warm backup (cloud / Git) solves "I want yesterday's version back". Cold backup solves "my account got locked" or "I accidentally deleted the whole GitHub repo". Run a weekly rclone snapshot to object storage — S3, Backblaze B2, Cloudflare R2 all work; B2 and R2 are cheap enough to ignore.

# Weekly snapshot, run from cron / launchd / Task Scheduler
DATE=$(date +%Y-%m-%d)
rclone copy ~/Documents/Kition r2:vault-backups/$DATE \
  --exclude ".kition/cache/**" \
  --exclude ".kition/index/**" \
  --progress

Heads up

Do not mount two cloud-sync clients on the same vault — you will get conflict files (document (conflict).md, document (computer-name).md). Pick one as the primary sync and use others as one-way cold backups. Time Machine and Windows File History are the ultimate safety net under any of these — they capture the last 30 days of point-in-time state and restore far faster than redownloading from the cloud.

Verify your backup actually works

An unverified backup is not a backup. Once a quarter, do a restore drill — restore the vault to a clean VM or a different directory, open it with Kition, and confirm docs, tables, and agent history all load.

• Markdown files open and render correctly
• .kitable tables query correctly; row count and field stats match (kition table check)
• Agent history replays
• Provider config is intact (API keys need to be re-entered — keychain does not migrate)