Override the Documents symlink in macOS

Overview

This is a handy little tool if you are a macOS user that also uses OneDrive. In my case, my family use OneDrive for document storage and what not as opposed to iCloud.

Requirements

• Ensure that the Documents and Desktop backup option is disabled.
• OneDrive should be installed, signed in to your account with the Desktop and Documents configured for backup.

Procedure

Change <TenantName> in the commands below to exactly match the folder name shown by your OneDrive account (e.g., OneDrive-Personal).

Caution: The following commands use sudo privileges and permanently remove the existing Documents folder. Ensure you have backed up any important data before proceeding. Only perform this action on a machine you own or have explicit permission to modify.

Pass the following block of commands to a terminal window from the user’s home directory.

# Step 1: Prepare the symlink command
ln -s ~/Library/CloudStorage/OneDrive-<TenantName> ~/Documents

# Step 2: Remove the existing Documents folder (requires sudo)
sudo rm -rf ~/Documents

# Step 3: Immediately recreate the symlink (use up arrow + Enter quickly after removing Documents)
ln -s ~/Library/CloudStorage/OneDrive-<TenantName> ~/Documents

# Step 4: Verify the symlink
ls -l ~/Documents

# Step 5: Test the symlink
cd ~/Documents
pwd

Conclusion

After completing this, you should be able to interact with the Documents folder as normal with the extra benefit of OneDrive archiving your documents as opposed to iCloud.