Clarify macOS volume type trade-offs and recommendations

[tobihagemann]

Updates macOS volume type documentation to provide clearer guidance on trade-offs between available options, based on feedback from @overheadhunter's community post (https://community.cryptomator.org/t/can-someone-explain-the-need-for-fuse-t/16040/2).

[coderabbitai]

Walkthrough

Edits are confined to docs/desktop/volume-type.md. The macOS/macFUSE section was reframed to present macFUSE as mature, update the project and installation links to macfuse.github.io and the releases/Getting Started pages, clarify that the macFUSE library is not bundled with Cryptomator, and add a note about Apple deprecating kernel-extension APIs since macOS 12.3 while explaining continued stability and mentioning FSKit as experimental. The FUSE-T section was reworded to warn about lower maturity, emphasize it as a user-space alternative avoiding kernel extensions, and add Homebrew install commands. The WebDAV (AppleScript) section now states no extra software is required, describes AppleScript-based mounting/unmounting, and notes expected localhost TLS warnings. Minor wording tweaks and link updates were applied; default mount paths were retained.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Areas to check closely:

• Validate updated macFUSE and macFUSE wiki links and installation URLs.
• Confirm accuracy of the macOS 12.3 kernel-extension deprecation note and FSKit mention.
• Verify the Homebrew commands for FUSE-T and their formatting.
• Ensure the WebDAV localhost TLS warning phrasing is correct and non-misleading.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Clarify macOS volume type trade-offs and recommendations" is directly and specifically related to the main change in the changeset. The raw summary confirms the updates focus on clarifying macOS volume type documentation by reframing guidance around macFUSE, FUSE-T, and WebDAV with better explanations of trade-offs and recommendations. The title is concise, clear, and accurately captures the primary objective without being vague or overly broad.
Description Check	✅ Passed	The pull request description is clearly related to the changeset, explicitly stating that it "Updates macOS volume type documentation to provide clearer guidance on trade-offs between available options." This directly matches the scope of changes documented in the raw summary, which shows updates to macOS volume type sections with improved framing and expanded guidance. The description is not vague or generic; it provides meaningful context by referencing community feedback that motivated the changes.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/clarify-volume-type-macos

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 97d7a4c and ddc5790.

📒 Files selected for processing (1)

• docs/desktop/volume-type.md (2 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/desktop/volume-type.md

[style] ~85-~85: Consider using “comfortable booting”.
Context: ...USE implementation for macOS. If you're comfortable with booting into recovery mode once to enable loadi...

(COMFORTABLE_WITH_VBG)

🔇 Additional comments (3)

docs/desktop/volume-type.md (3)

105-120: Good cautionary approach with actionable guidance.

The upgrade from a generic experimental note to a warning block is appropriate. The explicit Homebrew installation instructions are helpful, and advising users to switch to macFUSE when encountering issues provides clear fallback guidance. The emphasis on user-space execution and kernel-extension avoidance is a valuable distinction for users comparing options.

---

126-129: Clear explanation of software requirements and security expectations.

The explicit statement that no additional software is required improves clarity compared to the previous version. The explanation of why TLS warnings for localhost are expected is technically sound and helps users make informed decisions about whether this trade-off is acceptable for their use case.

---

84-99: All external links verified and documentation is technically accurate.

The macFUSE documentation section has been thoroughly verified:

• All referenced URLs (macfuse.github.io, GitHub releases, wiki pages, and issue #1025) are accessible and current
• GitHub issue #1025 ("Add support for the upcoming FSKit Framework") accurately describes the FSKit support referenced in the note
• Technical claims are accurate: macFUSE 5.0+ series (latest 5.0.7 as of Sept 2025) has experimental FSKit support for user-space operation without kernel extensions
• The reframing from warning to positive recommendation is well-justified given the active maintenance and forward path to FSKit

No changes required. The documentation is accurate and well-referenced.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/desktop/volume-type.md (1)

104-109: FUSE‑T Homebrew tap/package present — update install command

• Verified macos-fuse-t/homebrew-cask and macos-fuse-t/fuse-t repos exist and the project site is reachable. (github.com)
• Upstream homebrew-cask repo includes a Cask for fuse‑t and recommends installing with brew install macos-fuse-t/homebrew-cask/fuse-t (Homebrew index also shows brew install --cask fuse-t). (github.com)
• Current doc (docs/desktop/volume-type.md, lines 104–109) uses brew tap macos-fuse-t/homebrew-cask + brew install fuse-t — this will work after tapping, but update it to the explicit upstream command (recommended: brew install macos-fuse-t/homebrew-cask/fuse-t or add --cask) for clarity.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1126cb5 and 97d7a4c.

📒 Files selected for processing (1)

• docs/desktop/volume-type.md (2 hunks)

🔇 Additional comments (6)

docs/desktop/volume-type.md (6)

84-88: LGTM! Clear and balanced guidance on macFUSE.

The reframing from a deprecation warning to positive guidance is excellent. This provides users with clear expectations about macFUSE being the most mature option while acknowledging the recovery mode requirement upfront.

---

91-91: Updated link correctly points to macFUSE wiki.

The link change from the old osxfuse documentation to the current macFUSE wiki is accurate and helpful.

---

93-97: Excellent clarification on macOS API deprecation.

This note effectively addresses user concerns by explaining the macOS 12.3 API deprecation context while reassuring users that macFUSE remains stable despite requiring additional installation steps.

---

102-109: Clear positioning of FUSE-T with installation instructions.

The description accurately positions FUSE-T as a user-space alternative and the Homebrew installation commands are correct and helpful for users.

---

114-117: Appropriately balanced warning about FUSE-T maturity.

The warning is well-calibrated - it acknowledges FUSE-T's less mature status and provides clear guidance to switch to macFUSE if issues arise, without being overly discouraging.

---

123-127: Excellent explanation of WebDAV security warnings.

The documentation now clearly explains that WebDAV requires no additional software and provides valuable context about the expected localhost TLS warnings, helping users understand this is normal behavior rather than a security concern.

[overheadhunter]

I believe we can relax the "warning" of macFUSE even further, since the project seems to have a future.