Skip to content

iCloud Sync#

FoldNotes stores your notes in iCloud Drive, so they sync automatically across your devices.

How It Works#

  1. Files are the source of truth. Your notes are plain .md files in iCloud Drive. Any app or device that can read iCloud Drive can access them.
  2. Automatic detection. FoldNotes uses NSMetadataQuery to monitor the collection folder for changes. When a file is added, modified, or deleted on another device, FoldNotes updates its index.
  3. Incremental updates. Only changed files are processed — the entire collection isn't re-scanned on every sync.

Collection Location#

~/Library/Mobile Documents/iCloud~com~foldnotes/Documents/

This is the standard iCloud Drive container. Files placed here by any means (Finder, CLI, another app) are picked up by FoldNotes.

Conflict Resolution#

If the same note is edited on two devices before syncing, iCloud creates a conflict file. FoldNotes detects these and resolves them automatically when possible:

  • Identical edits are resolved silently — no user action required.
  • Non-overlapping edits are auto-merged — both sets of changes are combined.
  • Overlapping edits require manual resolution:
    • macOS — a conflict resolution panel shows both versions side by side, letting you compare and choose which to keep or merge changes manually.
    • iOS — an orange banner appears at the top of the editor with Keep Mine and Keep Theirs buttons. The editor is read-only until you choose a version.

Offline Access#

Notes are available offline — iCloud Drive keeps local copies of your files. Edits made offline sync when connectivity is restored.

Fallback#

If you're not signed in to iCloud, FoldNotes stores notes in a local collection at:

~/Documents/FoldNotes/

Notes stored locally won't automatically sync. Sign in to iCloud Drive to enable sync for new notes. If you have existing local notes, you will have to copy them.

On macOS, you can also specify a custom collection location using the CLI's --collection option.

SwiftData Cache#

FoldNotes maintains a local SwiftData cache for fast queries (tags, tasks, backlinks, search). This cache is derived from the .md files and is rebuilt automatically when needed. The cache is not synced — each device builds its own.

If the cache becomes stale, use File → Rebuild Note Index… to force a full rebuild.