OneDrive sync client deep dive

The OneDrive sync client is the engine that turns OneDrive and SharePoint libraries into folders on your laptop. For most users it just works, but knowing how it works helps a lot when it doesn't.

How sync works

The sync client uses a per-library agent that talks to Microsoft's OneDrive service. For each synced library, it maintains a local cache (under %USERPROFILE%\OneDrive - YourCompany on Windows, or ~/OneDrive - YourCompany on macOS). Changes upload as soon as the network allows; remote changes come down at similar speed.

The client supports:

• A user's OneDrive for Business (always synced once signed in).
• SharePoint libraries explicitly synced from a library.
• "Add shortcut to OneDrive" — adds a library as a folder inside OneDrive without a separate sync root.
• The user's personal OneDrive (separate app on Windows, integrated on macOS).

Files On-Demand

By default, files appear in the folder but aren't downloaded until you open them. Icons indicate state: cloud (online-only), green check (downloaded), green filled circle ("Always keep on this device"). This means you can have a 5 TB SharePoint library "synced" without filling your disk.

Files On-Demand uses cloud-files filesystem features on Windows and macOS, so other applications see the files normally — they're downloaded transparently on open.

"Add shortcut to OneDrive"

Microsoft's recommended pattern for shared libraries. From the library, click "Add shortcut to OneDrive" — the library appears as a folder inside OneDrive instead of as a separate sync root. This avoids many path-length and sync-troubleshooting problems and matches OneDrive's mobile and web experience.

Common pitfalls

• Long paths — Windows historically limits paths to 260 characters. OneDrive sync allows longer paths, but some apps (including older Office versions and some line-of-business tools) still don't. Keep folder depths reasonable.
• Filename characters — ?<>:"|*/\ are still illegal. Migration tools usually rename, but check.
• Conflict files — when two devices edit the same file offline, both copies sync and one becomes a conflict file. Co-author online to avoid.
• macOS performance with very deep file structures used to be poor; modern OneDrive on Apple Silicon is much better.

For IT, deploy via Known Folder Move, Silent Account Configuration, and Files On-Demand group policies / Intune profiles so sync just starts working on every user's first sign-in.