Journal · Engineering

Counting bytes on APFS

A file has a length. A volume has allocated storage. Deleting a file may change that storage by a different amount. On APFS, those are three separate questions, and a useful disk tool should keep the distinction clear.

01 Three numbers worth separating

MeasurementWhat it describesWhat it does not promise
Logical sizeThe length of a file's contents.How many unique physical blocks that file occupies.
Allocated sizeStorage the filesystem reports as allocated to the file.That none of those blocks are shared with another file.
Reclaimable spaceStorage that becomes free when no remaining references require it.That a directory scan alone can predict the result exactly.

For developers, stat exposes file length through st_size and allocated blocks through st_blocks. On macOS, those block counts use 512-byte units. These fields describe the file, not every reference elsewhere in the filesystem. See Apple's stat documentation.

02 Clones share data, not file identity

An APFS clone is an independent file that initially shares content blocks with its source. Changes use copy-on-write: the modified data gets separate storage while unchanged blocks may remain shared. Apple's APFS overview explains that behavior.

A clone has its own file identity. It is not another hard link to the original inode. Deduplicating inode numbers therefore does not, by itself, deduplicate APFS clones or measure the unique blocks that a particular deletion would free. Apple's clonefile documentation describes the separate attributes and shared data blocks.

As a simplified example, two unchanged clones can each report the full logical length while sharing their content storage. Removing one leaves the other intact and does not necessarily release those shared content blocks. Metadata and later edits make real cases more complex.

04 Snapshots retain earlier states

A snapshot can keep blocks available to an earlier filesystem state after the current file is changed or removed. This is another reason the difference in volume free space may be smaller than the size of a removed folder.

For Time Machine local snapshots, Apple says macOS counts their storage as available and reclaims it as needed. That management policy is useful, but it does not turn a live folder listing into a complete snapshot inventory. Read about local snapshots.

05 Cloud files can have a large logical size and little local data

A file visible in iCloud Drive may not be fully downloaded to the Mac. Its logical size can describe content held in the cloud, while its local allocation is much smaller. Opening or previewing a cloud file can cause a download, so metadata inspection and content access are different actions.

Use Finder's cloud status and the relevant download controls when deciding whether to retain a local copy. Apple distinguishes downloading an item from using Remove Download in its iCloud Drive guide.

06 How to use the numbers in Delve

Delve presents logical and on-disk size information alongside its visual maps. Use those measurements to understand the selected files and investigate large areas. Treat any reclaimable-space estimate as an estimate, especially when clones, hard links, snapshots, or inaccessible locations are involved.

We do not treat a folder total as a promise that the volume will recover the same number of bytes. The useful workflow is to inspect the path, understand the data, review the removal, and then compare available storage on the same volume.

07 A reliable way to compare readings

  1. Use the same volume and scan boundary for both readings.
  2. Check whether each tool shows logical size, allocated size, or available capacity.
  3. Check scan permissions and whether files changed during the scan.
  4. After a deliberate removal, check the Trash and compare the volume again.
  5. If the readings still disagree, investigate shared blocks, snapshots, cloud status, and container space rather than assuming that one label explains everything.

For a storage warning, continue with Mac disk full, but space is available?. For the design behind the visual map, read the architecture of Delve.

Common questions

Do APFS clones share an inode?

No. Clones are independent files that can share content blocks. Hard links, by contrast, are multiple directory entries for the same underlying file.

Does allocated size equal reclaimable space?

Not necessarily. Shared blocks and snapshots can retain data after one file is removed. A file-level allocation report is not an exact deletion forecast.

Does du show logical size by default?

On macOS, du normally reports allocated usage, not simply file lengths. APFS shared blocks can still make aggregated usage differ from uniquely reclaimable storage.

Keep exploring

← All journal