iCloud and iCloud Drive are confusing, no matter how you look at them. This is largely because of the illusions created to integrate iCloud storage into the Finder, and the tricks played to make it all work. This article traces how one file changes as it’s moved into iCloud Drive and handled there.

We start with a local file, stored in the Documents folder in our Home folder, when Desktop & Documents Folders are turned off, and not moved to iCloud Drive. For my purposes here, this file consists of four parts:

• the file’s attributes, including its name and an inode number that’s unique within the Data volume where it’s stored;
• its metadata, notably its extended attributes or xattrs, which might include information about the file’s origins, Finder tags, and more;
• its data, as a list of storage extents, and the data stored in those;
• its associated versions, if any have been saved in the macOS version database for that volume.

When that file is moved to iCloud Drive, the local file is moved within its directory tree to the Library/Mobile Documents/com~apple~CloudDocs folder in the Home folder. Although that’s hidden away, it’s in the same volume, so no copying is required, and all four parts of that file remain unchanged, from its inode number to its saved versions.

That’s copied up to iCloud Drive servers in a sync, but not everything goes with it. Instead of an inode number, iCloud assigns it a file number; all the data for the file is divided into chunks and uploaded, but its xattrs are filtered, and only some standard Apple xattrs end up in iCloud. No versions can be copied between different volumes or storage, so they don’t get copied up to iCloud Drive either.

If I have another Mac connected to the same iCloud account at that time, when that syncs, that file will be copied down to its local storage, but in the same form as it was in iCloud Drive, with a limited range of xattrs and no saved versions. Because that becomes a local file, that’s assigned its own local inode number.

Let’s assume that I have enabled Optimise Mac Storage, and then evict that file. What happens then is that the local copy of that file loses all its data, becoming a dataless file. However, there’s no change to the copy held on iCloud servers, which retains its full data.

If I now change my mind and need to use that document, its data has to be downloaded from iCloud Drive, and the local dataless file is materialised by adding its data back. That enables me to edit that file, and it can now be backed up by Time Machine, and searched for using Spotlight. Because that local file never lost its metadata, those remain intact, as should its versions.

When I’ve finished editing the local copy of that file, I save it, and that triggers iCloud to sync my changes back up to the copy of the file held in the iCloud servers. That could include changes in xattrs, but is mainly concerned with the changes in that document’s data.

If I were now to move that document out of iCloud Drive, back to the Documents folder where it started, as that’s within the same volume, the local copy of the file, complete with its metadata, data and any versions, would all move back into Documents, and the copy in iCloud’s servers would be deleted.

The whole process is summarised in this single PNG image.

Note that my local file, stored in ~/Library/Mobile Documents/com~apple~CloudDocs, remains the same file throughout, together with any changes I make to it during the edit. But that differs from the copy held in iCloud, and that copied down to a different Mac or device connected to the same iCloud account. Specifically:

• the file attributes contain different reference numbers (inode and iCloud file number), each being local to that storage;
• once the file leaves local storage, it travels with only some of its xattrs;
• when it leaves local storage, any saved versions are lost completely;
• if Optimise Mac Storage is enabled and the file is evicted, its data is removed from local storage, making it dataless. It can then be materialised by the download of its data from the copy held in iCloud servers.

I hope this provides you with better insight into how iCloud Drive works, and what its current limitations are.

Postscript

The bug affecting saved versions has now been fixed in Sonoma 14.4.1. Provided that files haven’t been evicted in 14.4, once your Mac is updated to 14.4.1, eviction shouldn’t result in the loss of local versions any more, and should behave as described above.

Amended 2005 GMT 25 March 2024 in the light of the bug in 14.4 being fixed in 14.4.1.