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#

Edits you make offline sync as soon as you reconnect — that part is automatic and needs no thought.

Reading offline is subtler. Your notes live in iCloud Drive, and iCloud Drive is allowed to remove the local copy of a file you haven't opened for a while when the device is short of space. The note still appears in your list, and FoldNotes can still show it from its cache, but the file itself has to be fetched — which needs a connection.

FoldNotes asks iCloud to download your whole collection at startup, so in ordinary use your notes are already local. That request isn't permanent, though: the system may evict them again later.

Keep your collection downloaded#

Recent versions of iOS and macOS added a per-folder setting that switches eviction off for good. FoldNotes can't turn it on for you — Apple provides no way for an app to set it — so it's worth doing once by hand:

Files → Browse → iCloud Drive → press and hold the FoldNotes folder → Keep Downloaded

Finder → iCloud Drive → right-click the FoldNotes folder → Keep Downloaded

Worth doing if you write on planes and trains, work anywhere with patchy coverage, or keep a large collection you want instantly available.

The cost is disk space: your collection's full size, permanently. For notes alone that's usually a few megabytes — it's images and attachments that make a collection grow.

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.