HolePunch
NAME
holepunch — A simple command line tool to punch hole to reduce disk usage on APFS volume for such as a raw disk image.
SYNOPSIS
holepunch [-pnvh] path
DESCRIPTION
holepunch is a simple command line tool that is using F_PUNCHHOLE to punch a region of the file at path that only contains 0x00 to reduce actual disk usage of the file on APFS volume.
The following options are available:
-p, --show-progress
Show progress while reading the file.
-n, --dry-run
Dry run. Do not actually punch hole.
-v, --verbose
Shows verbose messages.
-h, --help
Shows a help message.
USAGE
It requires macOS 11.0 and later also it only works for the files on APFS volume.
Install Xcode and build holepunch by using swift build command.
$ swift build -c release
Debug build may be very slow so recommend to use release build for actual usage.
EXAMPLES
On APFS volume, all files can be a sparse file, which unused area that only contains 0x00 can be not actually using a disk space.
For example, Docker Desktop for Mac creates a raw disk image file at ~/Library/Containers/com.docker.docker/.../Docker.raw on APFS volume.
If you use ls or such tool, its file size shows more than actual disk usage.
$ ls -l ~/Library/Containers/com.docker.docker/.../Docker.raw
-rw-r--r-- ... 60G ... .../Library/Containers/com.docker.docker/.../Docker.raw
The actual disk usage is much smaller than. You can see it by using du or such tool.
$ du -h ~/Library/Containers/com.docker.docker/.../Docker.raw
2.7G .../Library/Containers/com.docker.docker/.../Docker.raw
You can see this behavior on Finder by using “Get Info” menu item. It may show file size like “63,999,836,160 bytes (2.85 GB on disk)”.
This is because Docker Desktop for Mac is using same approach to punch hole where a part of the disk image only contains 0x00 to reduce actual disk usage.
See Disk utilization in Docker for Mac for more details.
However, Docker Desktop for Mac is, actually, often, somehow, suppose to do this online but often doesn’t.
This tool is actually reading the file and find a region of 0x00 and punch hole each region to actually reduce disk usage.
For example, after removing unused Docker images and stop Docker Desktop for Mac, run following command.
$ holepunch --show-progress ~/Library/Containers/com.docker.docker/.../Docker.raw
SEE ALSO
fcntl(2), copyfile(3)
