mount: support Windows using WinFsp (via mfusepy), fixes #2316

[ThomasWaldmann]

Fixes #2316.

borg mount now works on Windows, using WinFsp via mfusepy. mfusepy already knows how to talk to WinFsp's FUSE 2 API (it finds winfsp-x64.dll via the registry), so this is about the borg side.

What changes on Windows

• Mountpoint: WinFsp mounts on an unused drive (X:, X:\ is accepted, too) or on a directory that does not exist yet (WinFsp creates it when mounting and removes it when unmounting). do_mount checks for that instead of "existing, writable directory".
• No daemonizing (no fork): borg mount always stays in the foreground. Ctrl-C and Ctrl-Break unmount cleanly (rc 0, mountpoint gone, repository lock released).
• borg umount is not supported there and says so: WinFsp has nothing like fusermount -u (checked fsptool / launchctl), so the way to unmount is to stop borg mount (Ctrl-C / Ctrl-Break).
• Read-only: WinFsp silently ignores the ro mount option, a read-only volume has to be requested from the init callback (conn_info.want |= FSP_FUSE_CAP_READ_ONLY, via mfusepy's init_with_config).
• Owner / group: WinFsp makes a Windows security descriptor from uid / gid / mode and checks all access against it. Archived uids / gids do not refer to anybody on a Windows machine (one would be locked out of e.g. a 0600 file of uid 1000), so on Windows the uid / gid mount options are left to WinFsp (which then overrides owner / group of all files) and default to -1 = the user who mounts. UserName= / GroupName= also work.
• Volume label: volname (default borgfs for a drive, <dirname> (borgfs) otherwise), like we already do for macFUSE.
• Creation time: st_birthtime is given to mfusepy now (WinFsp uses it unconditionally as the creation time; harmless elsewhere, mfusepy ignores it if the platform's struct stat does not have it).
• readlink of something that is not a symlink fails with EINVAL, like readlink(2). WinFsp tries that for / when mounting to find out whether symlinks are supported - that gave an "Uncaught exception" traceback in the log.

Known limitations (documented in borg mount --help)

• WinFsp does not support hard link counts: st_nlink is always 1 (inode numbers of hard links are equal, though).
• Symlinks need a fix in mfusepy: WinFsp's struct fuse_operations has getattr, getdir, readlink, while libfuse (and thus mfusepy 3.1.1) has getattr, readlink, getdir. So WinFsp does not find our readlink, decides "no symlink support" and shows symlinks as regular files. With the two fields swapped for Windows in mfusepy, file / directory / dangling symlinks all work (verified). The tests here cope with both mfusepy variants. Fix for mfusepy: [fix] Windows: WinFsp has getdir before readlink in fuse_operations mxmlnkn/mfusepy#52. The WinFsp author confirmed that the different order "was an early accident that unfortunately no longer can be fixed due to backwards compatibility" (FUSE 2 API: struct fuse_operations has getdir before readlink (libfuse: readlink before getdir) - is this intended? winfsp/winfsp#693).

Tests

• fuse_mount() has a Windows branch (winfsp_mount()): it runs borg mount --foreground as a child process in an own process group and stops it with CTRL_BREAK_EVENT, i.e. like a user would do it.
• adapted expectations: hard link counts, EIO arrives as EINVAL (C runtime errno mapping), read-only check via GetVolumeInformationW (no os.statvfs), NTFS symlinks have st_size 0, test_migrate_lock_alive needs daemonizing.
• new: parse_mount_options tests (they run on all platforms), readlink EINVAL test for the mfusepy adapter, Windows-only test for the mountpoint / borg umount errors.
• CI: the Windows job installs WinFsp (choco install winfsp) and the mfusepy extra, so the mount tests run there and the Windows binary bundles mfusepy. This works on the GitHub runner: the mount tests ran there (19 passed, 4 skipped: ACLs are Linux-only, lock migration needs daemonizing).

How this was tested

Windows 11 Pro, WinFsp 2.1, MSYS2 UCRT64 (Python 3.14), mfusepy 3.1.1:

• manually: drive and directory mountpoints, file content (3 MB file, sha256), exact mtime / creation time, read-only volume (fsutil fsinfo volumeinfo), volume label, ownership, Ctrl-C / Ctrl-Break / kill behaviour, mountpoint validation errors.
• mount_cmds_test.py, vfs_test.py, fuse_test.py: 42 passed with -n4, with python -m borg and with a PyInstaller-built borg.exe (one-dir and single-file both mount and unmount fine), with released and with fixed mfusepy.
• Linux (Debian 13), same test files: 42 passed with libfuse 2.9 and with libfuse 3.17.

Not tested: using the mount from the Explorer of an interactive desktop session (everything was done via ssh).

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 80.85106% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.22%. Comparing base (7a16a03) to head (e6de95d).
⚠️ Report is 5 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/borg/archiver/mount_cmds.py	64.70%	2 Missing and 4 partials ⚠️
src/borg/vfs.py	88.88%	2 Missing ⚠️
src/borg/hlfuse.py	91.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #10391      +/-   ##
==========================================
+ Coverage   88.19%   88.22%   +0.03%     
==========================================
  Files         103      103              
  Lines       18822    18865      +43     
  Branches     2919     2931      +12     
==========================================
+ Hits        16600    16644      +44     
+ Misses       1548     1544       -4     
- Partials      674      677       +3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.