Two numbers that should not go together
Pick a file in Finder, press Command and I, and look at the size. Once in a while you see something that looks like a typo: 31 GB at the top, and next to it, in brackets, zero bytes on disk.
My first reaction, the first time I saw it on a Baseseat mount, was that something had broken. A 31 GB file cannot take no space. Then I opened it, scrubbed through it, and it played. Nothing was broken. Both numbers were telling the truth, and the gap between them is the whole idea of this post.
I did not know any of this was possible until I had a reason to care. I used to think a file was a thing you had, the way you have a book on a shelf. Then I spent an afternoon waiting on a download bar for a very long screen recording, and realised I wanted four minutes of it. Why was I carrying the whole book home to read one page?
The first number is how big the file is. The second is how much of it your laptop is holding. For almost every file you have ever owned those two matched, so you never had to think about the difference. They do not have to.
A folder that shows everything and holds almost nothing
When you mount a Baseseat drive, it appears as an ordinary folder with ordinary files in it, each at its full size. Your video editor sees a 31 GB file. Your terminal sees a 31 GB file. Neither is being lied to, exactly. The file really is that big. It just is not on your machine yet.
Nothing downloads until a program reads something. And when one does, it gets only the part it asked for, fetched in blocks of 8 MiB. If a program reads the first few kilobytes of a file, the mount brings over one block. If it jumps to the middle, it brings over the block that holds the middle. The rest stays where it is.
Think of a library with a very good lending desk. The catalogue lists every book at its real page count, so you can see all of it. But you leave with only the chapters you asked for, handed over in 8 MiB stacks, and the rest stays on the shelf. Whether you borrow one stack or fifty is up to you.
If you have ever watched a video start playing before it finished downloading, you already understand this. The difference is that it works for any file and any program, because the program is not doing anything special. It is just opening a file, and asking for bytes at some position, the way programs have always done.
What the cache does
Parts you have read stay on your machine in a local cache, so reading the same part twice does not go back over the network. The cache holds 10 GiB by default. You can change that when you mount, with the `--cache-size` option, and the smallest it will accept is 256 MiB.
So the zero bytes on disk is where you begin, not where you stay. Watch a clip from the middle of that 31 GB video and the blocks you watched will be cached. Finder's second number will creep up from zero, and it will stop growing when the cache is full. The cache has a ceiling, so a laptop with a modest drive can work on a file far larger than the drive, as long as it does not need all of it at the same moment.
That last sentence is the practical point. We have all met the moment when a download will not finish because the disk is full. A mount moves the limit from how much you can store to how much you are reading right now.
Three things this is good for
The tail of a huge log. You do not want the log, you want the last forty lines, and a minute ago something went wrong. Open it with tail and the program asks for the end of the file. One block comes across, not the 20 GB of last month's noise in front of it.
A long video. Scrubbing along a timeline is just a series of jumps to different positions. Each jump fetches the blocks around it, so you can find the take you want in a long recording and cut a clip with ffmpeg without having pulled the whole file down first.
A big Parquet file. Columnar formats keep their index at the end and their columns in separate stretches, precisely so that a query can read a little of the file and skip the rest. Point DuckDB at one through a mount and a question about two columns brings over roughly those two columns. The format was designed for this. The folder just stops getting in the way.
None of these needed a special tool, which is rather the point. The programs involved are the ones you already use, doing what they always did, and the folder behaves like a disk that happens to be very large.
When there is no mount
Not every machine can mount a folder. Windows cannot, and a lot of cloud sandboxes will not allow it. The same idea still works from the command line.
`baseseat file cat ID --bytes A-B` prints a range of bytes from a file and nothing else. If you only need lines, `baseseat file read ID --start-line 40 --line-count 20` gives you those twenty. And `baseseat grep PATTERN` searches the whole drive without you fetching a single file.
For tools that want a URL, `baseseat file link ID` makes a short-lived link, good for 15 minutes by default, that answers HTTP Range requests. That is the request a program makes when it says give me bytes A to B of this. ffmpeg knows how to speak it, and so does DuckDB, so both can seek into a file that is still sitting on the drive. Same trick, different doorway.
I find the link version most useful when I am scripting something I do not want to mount: a one-off query over a file I will never open again. It is a command, a URL, and a tool that already knows how to ask for ranges. Fifteen minutes later the link stops working on its own, which is about the right amount of loose end to leave behind.
Writing works the same way
It would be a strange sort of half-feature if you could read a 31 GB file in pieces but had to upload all 31 GB again to change one line. You do not.
Append a line to that big log and only the new bytes travel. Patch a few bytes in the middle of a binary file and only those bytes go. From the command line, `baseseat file patch` writes bytes at an offset, or appends, and `baseseat file edit` replaces exact text. In a mount, you save the way you always have, and the change goes back by itself once the file has been quiet for a couple of seconds.
Every write is saved as a new revision of the file, and a write has to say which revision it was based on. If someone else changed the file in the meantime, the write is refused, nothing is written, and the program reads the newer version and does its change again on top. That costs a moment. It also means two people, or two agents, patching the same file cannot quietly erase each other.
Deleted files go to the drive's trash and can be restored for an hour, so a slip with a large file is not a disaster. I have needed that more than I would like to admit.
The honest part
This is not magic, and I would rather you heard the limits from me.
The first read of any part has to come over the network. If you are on a slow connection, the first scrub through a video will feel like a slow connection. The second pass will be fast, because by then the blocks are on your disk. A fast cache helps a repeat visit. It does nothing for a first one.
And if a program really does need every byte, nothing is saved. Run a checksum over the whole 31 GB file and all 31 GB comes across, because that is what you asked for. The mount makes the small question cheap. It cannot make the big question small.
A mount needs macOS, or Linux with FUSE. On Windows, `baseseat pull` and `baseseat push` keep a working copy instead, which is a different bargain: you hold the files you pulled, and only changes travel back. It suits some jobs well. It is not the zero-bytes trick.
What I like about it is mostly that you stop thinking about where the file lives. You open it, the program reads what it reads, and the folder deals with the rest. The zero bytes on disk is just what it looks like when nobody has asked for more than they need.