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)