After the Optimise Mac Storage control, iCloud’s other important setting is whether to locate your Desktop & Documents Folders in iCloud Drive. Since this was introduced some years ago, Apple has shown so much enthusiasm for its use that it’s repeatedly offered as a default, for instance when upgrading macOS. However, its effects may prove surprising, and its implementation remains controversial. This article looks at what it does, how it works, and briefly revisits iCloud’s chunking service.

For the sake of simplicity, all results here were obtained with Optimise Mac Storage turned off, so making iCloud Drive a replicating FileProvider. Its behaviour with Optimise Mac Storage turned on is similar, except that files can then be evicted by the user or macOS, making its effects even more complex.

Move Desktop & Documents Folders to iCloud Drive

The effect of turning Desktop & Documents Folders on is to upload all items in the current Desktop and Documents folders, and to move those two folders into the iCloud Drive location in the Finder. Locally this is accomplished by moving the files in those folders into a different location in the Home folder, a quick process as they remain within the same APFS volume. To the user, this appears as if the Desktop and Documents folders have been removed from their standard locations, and have been lost from the standard folder layout. An alert does warn the user what has happened, but too late to offer an escape route if they have second thoughts.

The time required to complete this process is thus largely dependent on how long it takes to upload all the files in the two folders, which in some cases may be several hours or more.

Among the first log entries marking the change is a series from FileProvider that explain some of the mechanism involved in setting this up:
[INFO] 🅿️ Registered file provider extension […] for path […]
moving aside existing target folder […] for detachRoots […]
move detached folders to relocated location for detachRoots […]
create relocation symlink from ~LMD/c{17}s/D{5}p to ~/D{5}p
create relocation symlink from ~LMD/c{17}s/D{7}s to ~/D{7}s
merging old folder into relocated folder […]

This almost immediately results in a queue of events to be processed that exceeds the capacity to process them, and FileProvider repeatedly reports this in entries such as
[WARNING] We still have too many events in the queue, blocking until events are flushed

This heralds a torrent of changes to directory trees, marked by
┏fdd5 👁 processing FP tree changes
[INFO] received notification that provider info has changed; scheduling a fetch

Those finally complete, as does the upload of files to iCloud Drive to populate its copy of the folders.

Chunking by MMCS

This presented an opportunity to see iCloud’s chunking service MMCS in action on many files. I have previously reported that it appears to divide files for upload into chunks of no more than around 15,350 bytes in size. However, it here behaved quite differently.

While a minority of files to be uploaded were still divided into those small chunks, in this case with average chunk size ranging between 13,583-14,246 bytes, the majority of files were uploaded in just 1 or 2 chunks of larger size of up to 4,257,238 bytes (4.2 MB). Those are well within the reported maximum chunk sizes for the service, of 28-33 MB. It’s unclear how MMCS determines which files to send in larger chunks, though.

Remove Desktop & Documents Folders from iCloud Drive

Unexpected behaviour is seen when the user turns off the setting to put Desktop & Documents Folders into iCloud Drive. Instead of moving the folders back from the iCloud Drive location to their original location, macOS creates fresh and empty folders in the regular Home folder. Although the contents of the previous Desktop and Documents folders are retained in iCloud Drive, when seen from their Mac, the user may believe that those entire contents have been deleted, despite an alert that tries to explain what will happen. At least this time the user is offered a way back to reconsider their action, although it’s unclear what other option they might have.

When turned off, those folders are removed with all their contents, which remain in iCloud Drive, but are absent from the empty local Documents and Desktop folders.

The saving grace to this counter-intuitive behaviour is that, despite their apparent movement, the files themselves have remained within the same volume throughout the process of ‘moving’ to iCloud Drive, and ‘vanishing’ on their return journey. As they retain the same inode numbers at each stage of these processes, when they’re finally ‘moved’ manually back into ~/Documents and ~/Desktop, they have remained intact, complete with all their extended attributes and any saved versions. Thus their ‘movements’ preserve both data and metadata at all times.

Entries by FileProvider in the log mirror those of turning this feature on, recorded here as deregistering extensions:
[INFO] 🅾️ Deregistered file provider extension […] for path […]
[INFO] 🅾️ Deregistered file provider extension […] for path […]
[INFO] received notification that provider info has changed; scheduling a fetch

Following those, necessary tree changes are made in another torrent of entries by FileProvider,
┏11122 👁 processing FP tree changes
and the syncing of those changes.

With Optimise Mac Storage turned off no download of file data takes place, and moving the contents from iCloud Drive back to populate the local ~/Documents and ~/Desktop folders also occurs without any need for file syncing or copying.

Does this work?

Throughout the macOS human interface, users expect that turning features on and off are complementary, in that whatever change resulting from turning something on is reversed when it’s turned off again. No matter how much engineering sense the Desktop & Documents Folders setting might make, this remains one of the few controls that continues to drop users into abject panic. Displaying terse and opaque alerts can never prevent raw human emotion in response to what appears to be the deletion of their entire Documents and Desktop folders.

As it turns out, the engineering solution ingeniously preserves the integrity of all the files involved, even down to extended attributes and saved versions. But that is no compensation for what otherwise might look like a very malicious prank. If there’s one feature in iCloud Drive that functions as aversion therapy, and deters users from trusting iCloud, it must be putting Desktop & Documents folders in iCloud, and taking them back.

Summary

• Putting Desktop & Documents Folders in iCloud Drive transfers the whole contents of those folders into equivalents in the iCloud Drive location, and requires all those files to be uploaded, which can take a long time. However, local copies of files are only moved within the same volume, so retain all their original data and metadata.
• Removing Desktop & Documents Folders from iCloud Drive by turning this setting off creates new and empty ~/Documents and ~/Desktop folders, and leaves their copies in iCloud. Although it may appear that this removes all local files, in fact they remain in local storage, with all their original data and metadata intact, and can be moved back into their original folders without requiring further downloads.
• Turning this setting on and off aren’t complementary procedures, in that files aren’t returned to their original location, and users may assume that they have been deleted and lost.
• Although technically correct and ingeniously engineered, this remains disastrous in terms of its human interface.
• Chunking of files for upload by MMCS may use small chunks of no more than around 15 KB, or larger chunks of up to 4.2 MB. I don’t know how MMCS chooses between them.