Global Cache docs are harmful to macOS adoption due to incorrect statement about clonefile using more disk space

[rtharston]

What is the type of issue?

Documentation is incorrect

What is the issue?

It is incorrect, and harmful to the adoption of Bun, to say that This benefit does not extend to macOS, which uses clonefile for performance reasons. in the global cache documentation.

On APFS drives cloning a file just points the new file at the blocks for the old file, so no extra space is used on your drive. Only when one of the two files change in some way are the 'dirty' blocks copied and the other blocks are still shared (COW in computer storage).

It is actively harmful to say the files are duplicated because some people see this as a blocking issue to using Bun, thinking that they'll end up wasting lots of space on their modules in their projects. The person in this YT video says he won't use Bun on macOS only because of this issue, and the video has over 114 thousand views as I write this.

First, the behavior should be verified to ensure that cloning the files is using APFS to just make clones. If that isn't the case, a new issue should be made to fix that. Bun should be using APFS clones, no exceptions.
Second, the documentation should be updated to say that on APFS drives (which is the vast majority, only old machines using hard drives might be on HFS still) clonefile is used, but the files still don't take up more space, and only if they are still on HFS (which again, is very unlikely today) will this mean they are taking up more space.

(I would do the verification step for you right now, but I won't have the time at the. moment unfortunately.)

This blog post has some great info about this:
https://eclecticlight.co/2020/04/14/copy-move-and-clone-files-in-apfs-a-primer/#:~:text=APFS%20clone%20files%20(%27copy%20on,same%20data%20as%20the%20original.

Where did you find it?

The documentation:
https://bun.sh/docs/install/cache#:~:text=it%20uses%20clonefile%20.-,Saving%20disk%20space,disk%20space%20dedicated%20to%20node_modules%20.

Again, the highly viewed video that mentions this:
https://youtu.be/dQkv5C-Lfkw?si=tRUoiBs54Y63f87b&t=500

[ImBIOS]

+1 Well Played... I mean... Well Researched.
I don't know much, but I support this research and idea.

Storage "trauma" is blocking me adopting bun fully. MBP with huge storage is still expensive to my pocket.

UPDATE:
I actually tested in my MacOS and Linux (Debian) in MacOS (using OrbStack), both are conguering storage. I don't know why. This topic need to be addressed on top priority, it's urgent for adoption.

[Jarred-Sumner]

You’re right that it doesn’t actually consume space

But the issue is the accounting. macOS treats clonefile as consuming more space even if it doesn’t actually

[rtharston]

Properly accounting for 'free' space in APFS is complicated, yes, and macOS needs to do better at that, but I'm not sure what that has to do with correcting Bun's docs. Bun need not, and should not participate in and propagate the poor accounting practices of the Finder in macOS.

The reality is that cloning a file does not use more space on your drive, and people should be educated on what is actually going on so they aren't scared away by thinking that using Bun is going to eat up all their precious disk space when it isn't. (And they should be aware when it actually is using their disk space.)

[ImBIOS]

What's the actionable plan then? After reading this, I totally migrate from pnpm to bun, and even using bun in my nextjs standalone deployment with this custom bun-node docker:

• https://github.com/ImBIOS/bun-node

[Electroid]

To resolve this, I think we'll want to write a brief note about how Finder will double-count the disk space, even though it doesn't. But let's not make it an essay.

[ImBIOS]

After researching further this, it's already been a month since I completely migrated to Bun without any hesitation. Thanks for the information.

[CallMeLaNN]

Today, I was considering Bun again for my next project since the #250 Vite that I follow was fixed. After quickly going trough the docs and getting some feel of how far the compatibility with Nodejs things that I'm familiar with, I think it's worth the try.

Then I saw the same statement on the doc. Since I'm using Mac and pnpm, I almost wanted to forget about bun. After quickly research about clonefile I got the same conclusion as of above. The interesting part is I found this issue without bun keyword on my search. I feel 💆‍♂️ and can proceed to try all my toolings and be familiar with bun cli.

Regardless of the implementation of clone on Mac, the claim on the doc quite strong which I agreed about the concern from OP and that statement has to be fixed because reader quickly guess it refer to the opposite of pnpm that is copy files on deep node_modules.

[ImBIOS]

pnpm/pnpm#5001

Fyi, the next release of PNPM will also use clonefile.