Wild horses finally dragged me back to iCloud last week, to look at some important topics that always seem to cause confusion: Spotlight search, Time Machine backups, file recovery, document versions, and extended attributes. It’s not surprising that even part way through, you were complaining how complicated iCloud is, and how opaque. I don’t think it is, it’s just that Apple doesn’t anywhere explain what iCloud does, and how it does it.

Its front page for those services is immaculately designed, and links through to crystal clear sets of instructions, some containing quite detailed information about different aspects. But nowhere can I see anything apart from how-to recipes. For example, the last of those pages contains the warning that you should “avoid storing app folders, libraries, .tmp, .vmdk, .vmware, .vbox, .vm and .pvm files in iCloud Drive.” Yet there’s no explanation, and no rationale given. What does Apple mean by an app folder? I presume the file extensions given there are intended to include virtual machines, but that’s a considerably larger category, and without guessing that, how would I know whether other virtual machine files were ‘safe’? I also see various comments in discussion forums that iCloud Drive blocks files with certain extensions from being uploaded at all, although Apple doesn’t appear to mention that.

Apple does provide a dedicated iCloud User Guide, but where I’d expect to find a conceptual introduction there’s just a warren of how-tos and nothing to explain key concepts such as eviction or any of the topics that I’ve covered in the last week.

At one time, Apple used to write excellent conceptual guides for developers. While there’s extensive information about using CloudKit from third-party apps, the iCloud Design Guide was last updated at the end of 2015, and much of its content was originally written a decade ago. Apple’s two major frontline guides, covering Platform Security and Platform Deployment, tell us all about encryption and the protection of data in iCloud, and a wealth about MDM, but next to nothing about what or how iCloud does.

For the knowledgeable user, iCloud and iCloud Drive thus consists of a set of instructions, a bit like a recipe book. There’s no rhyme or reason to them, no underlying principles, nothing that can be used to tackle a problem that isn’t already covered by a recipe. For a service that’s probably used by as many as a billion people around the world, that isn’t what I’d expect.

Once you understand how eviction and iCloud’s concealed stub files work, iCloud Drive’s behaviour with Spotlight search and Time Machine backups becomes perfectly logical rather than appearing random. When a file has been evicted, or its ‘download has been removed’ as Apple describes it for users, its stub file can’t be used for search or backup unless the file is downloaded again. As there’s no guarantee that download could be achieved, rather than hold up the whole search or backup, evicted files are simply omitted. As far as I’m aware, this is the common solution to similar problems with other cloud storage services.

What I had struggled with in the past were document versions and extended attributes. I don’t know whether I simply became confused by the apparent discrepancies in the results of my previous tests, but I think at last I understand why these behave the way they do in Ventura (which may itself have simplified behaviour).

As with locally stored document versions, macOS doesn’t try to store or transfer old versions of documents in iCloud Drive. Instead, prior versions accessible from any connected system are those it has stored locally in its own saves. This has the significant disadvantage that those versions created using a different system are only accessible from that computer or device, but it has clarity and consistency. If you want to access or transfer versions saved to another system, then my free utility Revisionist is a proven and robust way of doing so, and is now compatible with Sonoma.

Extended attributes (xattrs) are more complex, though. When accessed from the same system that uploaded them, macOS ‘cheats’ by using the xattrs stored in its local file system metadata, so appears to retain almost all types, apart from large xattrs and Resource Forks if the file has been evicted and downloaded again. But the list of xattrs that are actually transferred in iCloud Drive to other systems is far shorter, and depends on xattr flags and default behaviour for that type. Unfortunately, that does mean that almost all third-party xattr types don’t survive transfer by iCloud Drive, but that’s under the control of those apps that write their own xattrs. My own integrity-checking utilities, including cintch, Dintch and Fintch use the correct flag to ensure that they are sticky and are retained.

There’s no reason that other apps can’t do the same, except of course that Apple has only ever documented its xattr flag system in source code, which brings me back to my starting point about documentation.