File share to SharePoint migration: permissions, paths and versions

Assess the share against SharePoint Online limits first

Run the assessment before designing anything, and run it against the destination library path, because the path limit is measured at the destination. A share rooted at \\fs01\finance landing in /sites/finance/Shared Documents gains that prefix on every item.

Two findings deserve a decision rather than a fix. Folders above the 5,000-item threshold will migrate, but users will hit view limits until indexed columns exist, so it is often better to split them on the way across. And PST files are frequently the largest things on a file server; they are mail archives, and SharePoint is the wrong home for them.

NTFS permissions: what maps and what to flatten

NTFS permissions do not translate one to one. SharePoint has permission levels (Read, Contribute, Edit, Full Control and custom levels) applied to users and groups at the site, library, folder or item, and every scope that differs from its parent is a unique permission scope that SharePoint has to store and evaluate. A file server with per-folder ACLs everywhere will produce thousands of them, and each one is a scope the assessment should count before you decide how to map it.

A workable approach, in order:

1. Audit the source ACLs and list every principal: domain users, domain groups, local groups, orphaned SIDs. The assessment should report unresolved and disabled users and orphaned SIDs so you can decide on them up front.
2. Map principals to Entra users and groups by UPN first, then mail, then display name, with a CSV override for the rest. The Migration API only accepts UPN logins; non-UPN emails cause unexpected behaviour, and anything unresolved is written as the System Account unless a fallback is supplied.
3. Map NTFS rights to SharePoint permission levels: Read to Read, Modify to Contribute or Edit, Full Control to Full Control. Decide what to do with Deny entries, which SharePoint does not have; usually the answer is to remove access instead.
4. Flatten. Grant at the library or top-level folder wherever the source ACLs are effectively the same below that point, and keep unique permissions only where they genuinely differ. Fewer scopes means faster SharePoint and fewer surprises.
5. Copy unique permissions after import. ShareShift writes broken-inheritance permissions on folders and files after the Migration API import, with users mapped and SharePoint groups matched by name, and reports anything it could not resolve.

Timestamps, authorship and versions

A file share has a created time, a modified time and an owner, and no version history. The Migration API can set Created, Modified, Author and Editor on each imported item, so the destination library shows the real dates and people rather than the migration date and the migration account. That depends entirely on the user mapping: an author who cannot be resolved to a destination UPN falls back to the account you nominate.

Versioning starts at the destination. SharePoint Online libraries version by default, so the migrated file becomes version 1.0 and every later edit adds a version. On incremental passes this matters: a file that changed at the source since the last run is uploaded as a new version on top of the destination history rather than replacing the file, and Created, Modified, Author and Editor are restored on the new version. Resubmitting through the Migration API would replace the file and all its versions, so incremental updates go through a different REST path.

One property does not fully survive: setting the Editor on an imported item updates what library views show but not the underlying file-level modified-by property, which stays as the app. Author is applied to both. Tell content owners this before they notice it.

How the bulk copy works

For file-heavy workloads the right path is Microsoft's SharePoint Import Migration API, the same mechanism ShareGate's Insane mode uses. The worker packages content locally, encrypts it, uploads it to Microsoft-provided Azure containers in the destination tenant's datacentre, submits a job, and polls for the result.

• Packages are sized to Microsoft's guidance of 100 to 250 MB or about 250 items; single large files get their own package; fewer than 5,000 jobs are queued per tenant.
• Every blob is encrypted with AES-256-CBC and a per-blob IV before upload, and the job is created with CreateMigrationJobEncrypted. Containers are provisioned by SharePoint at no extra cost, are encrypted at rest, and are destroyed after the job.
• Progress comes from GetMigrationJobProgress; Microsoft is deprecating the older Azure Queue status route in the second half of 2026.
• Microsoft's own per-job logs are encrypted with the package key and are the only place the real error detail lives, so the worker downloads and stores them for every job.
• Traffic is decorated ISV|Company|Product/Version and Retry-After is honoured on 429 and 503.

Measured on 7 September 2026: 2,500 files in 10 packages with 4 in flight took 8 minutes 16 seconds end to end with zero throttling responses. The first concurrent batch produced 40 transient item-level import errors (about 1.6 percent) which the automatic retry pass cleared. That is a small sample on one tenant, not a benchmark; plan from Microsoft's bands of 1 TB a day for Office-file content per tenant. The throttling article explains why adding workers does not add budget.

shareshift assess \\fs01\finance --library "/sites/finance/Shared Documents"
shareshift migrate \\fs01\finance --site https://contoso.sharepoint.com/sites/finance \
  --library "/sites/finance/Shared Documents" --user-map users.csv --fallback-user admin@contoso.com

Step by step

1. Assess the share against the destination library path. Fix or decide every blocker; note the warnings.
2. Design the destination: which shares become which sites and libraries, where deep trees get flattened, which folders over 5,000 items get split.
3. Build the user mapping CSV and pick a fallback account. Verify mapped users exist at the destination.
4. Pilot one share or one top-level folder. Check dates, authors, permissions and a few files opened by their owners.
5. Run the bulk pass while users keep working on the share. Schedule it into nights and weekends if the tenant is busy.
6. Run incremental passes; unchanged items are skipped, changed items become new versions, new items are added. Pick a conflict rule for anything edited at both ends.
7. Cut over: make the share read-only, run a final incremental pass, point users at the library, and keep the share read-only for a retention period.
8. Export the item-level report and the HTML completion record, reconcile counts, and file them. The completion report article explains what to keep.

If the source is a plain file server with no restructuring and no assessment needs, Microsoft's free Migration Manager is a legitimate choice and has delta sync for file shares. The reasons to use a paid tool are the assessment up front, permission mapping you can review, pause and resume, and a completion report; the roundup of tools sets out the trade-offs. ShareShift covers all of that on the Monthly plan for a single project, and the pricing page has the figures in your currency along with the 30-day trial.

Frequently asked questions