APFS has extensive support in the tools bundled in macOS. Its GUI app Disk Utility provides regular users with fairly comprehensive features, although some of them have been plagued by bugs, such as that making some attempts to run First Aid on APFS volumes and containers fail because they haven’t been unmounted by Disk Utility. As there’s no third-party substitute, it’s not possible to compare results obtained by Disk Utility against those of a competitor.

This article instead concentrates on Apple’s command tools, starting with its checking and repair. Some of these commands may require elevated privileges using sudo; because that isn’t easy to predict, I only add that as a preface where I believe it’s always required.

Check and repair with fsck_apfs

First Aid in Disk Utility relies on running the command tool fsck_apfs, but only provides fixed options. If you want more flexibility, use the command directly in Terminal. You first need to identify the device name of the volume to be checked, such as disk3s1, and discover whether it’s encrypted. Unlock an encrypted volume without mounting it using a command like
diskutil apfs unlockVolume /dev/disk7s2 -nomount
Other volumes and containers should be unmounted first using diskutil unmount followed by their device name.

fsck_apfs has valuable options, including:

• -S : to skip checking of snapshots
• -n : to check but not to repair
• -y : to attempt to repair all errors found
• -q : to perform a quick check to verify whether the superblock and checkpoint superblock are valid.

Typical commands used include:

• sudo fsck_apfs -n /dev/disk7s2 just to check the volume disk7s2 but not repair it, including its snapshots.
• sudo fsck_apfs -y /dev/disk7s2 to check and repair all errors automatically, including its snapshots.
• sudo fsck_apfs -n -S /dev/disk7s2 to check but not repair, excluding all snapshots.
• sudo fsck_apfs -n -S /dev/disk7 to check but not repair the container disk7, excluding all snapshots.

Apple has consistently advised that checks and repairs should be performed in the order volumes, containers, then disks, although in other file systems the reverse is more usual.

Get information with diskutil

For those content with using Disk Utility to create and maintain APFS containers and volumes, diskutil still has commands that can be of great value in obtaining information about the file system. These include:

• diskutil list : provides a short summary, useful for discovering device identifiers
• diskutil info -all : provides a full listing with extensive information
• diskutil apfs list : provides a full listing of APFS container and volumes
• diskutil apfs listVolumeGroups : lists all mounted volume groups
• diskutil apfs listUsers / : lists cryptographic (Secure Token) users for the current boot volume group.

Main tools in diskutil

diskutil apfs provides an extensive range of verbs for working with APFS. Detailing them all here is neither feasible, nor can it keep pace with changes. As the man page, informative though it is, also falls out of date, usage information should be obtained using
diskutil apfs [verb]
for any verb that the user is unfamiliar with. A full listing of verbs is available with diskutil apfs, and currently includes:

• list : shows the status of all current containers (see above)
• listUsers : lists cryptographic users/keys of a volume (see above)
• listSnapshots : lists snapshots in a mounted volume
• listVolumeGroups : lists all current volume group relationships (see above)
• convert : nondestructively converts from HFS+ to APFS
• create : creates a new container with a single volume
• createContainer : creates a new empty container
• deleteContainer : deletes a container and frees or reformats disks
• resizeContainer : resizes a container and its disk space usage
• addVolume : adds a new volume to a container
• deleteVolume : removes a volume from its container
• deleteVolumeGroup : removes a volume group from its container
• eraseVolume : erases the contents of, but keeps, a volume
• changeVolumeRole : changes the Role metadata flags of a volume (see below)
• unlockVolume : unlocks a locked and encrypted volume
• lockVolume : locks an encrypted volume
• changePassphrase : changes the passphrase of a cryptographic user
• setPassphraseHint : sets or clears the passphrase hint of a cryptographic user
• encryptVolume : enables FileVault encryption
• decryptVolume : disables FileVault encryption
• deleteSnapshot : remove a snapshot from a volume
• defragment : arms or checks status or begins defragmentation
• updatePreboot : updates a volume’s related Preboot volume (see below)
• syncPatchUsers : copy a volume group’s crypto users in System-to-Data role (see below).

diskutil apfs changeVolumeRole takes arguments for the volume device (e.g. disk5s1) and one or more letters specifying the role. Roles are given as:

• clear : to clear all roles
• lower case letters b|r|v|i|t|s|d|e|x|h|c|y to clear that role
• upper case letters B|R|V|I|T|S|D|E|X|H|C|Y to set that role

Ownership of the specified volume is required for this to work. Roles supported include B (Preboot), Recovery, VM, Installer, T (Time Machine backup store), System, Data, E (Update), XART, Hardware, C (Sidecar, Time Machine), and Y (Enterprise, data).

diskutil apfs updatePreboot takes an argument for the volume device (e.g. disk5s1) with further options given in its usage information. This will “examine the given APFS Volume for macOS and Open Directory (OD) database files, correlate the Volume’s APFS crypto users with OD users, and update the related Preboot Role Volume’s Subject Directory with data such as EFI login graphics. Specifying “/” for its overrideODFullPath option will use /var/db/dslocal/nodes/Default. No crypto passdata is needed, but ownership of the affected disks is required.”

diskutil apfs syncPatchUsers takes an argument for the volume device (e.g. disk5s1). This “expects the given APFS Volume to have a System role, be a member of an APFS Volume Group which also contains a Data role sibling Volume, and be a macOS installation with zero or more APFS Crypto Users. All APFS Crypto user unlock key data records are duplicated from the System to the Data role volume. You can use this verb to recover from certain rare circumstances. No crypto passdata is needed, but ownership of the affected disks is required.”

Apple doesn’t explain any further what those “rare circumstances” might be.

Unlock FileVault Data volume with apfs_unlockfv

In addition to diskutil apfs unlockVolume, this separate command can be used to unlock an encrypted FileVault data volume using a password. If a path is given as its argument, it will try to unlock the volume containing that path in a mounted Data volume. The option -W given before the path will try to unlock using an empty password. If no path is given, then it will try to unlock the Data volume for the current root file system.

Convert HFS+ file system to APFS with apfs_hfs_convert

Apple recommends that HFS+ volumes are converted to APFS using diskutil apfs convert where possible, but this command provides a more extensive range of options, including:

• -D : convert all former and current directory hard links to files/aliases
• -e : estimate the size of apfs metadata
• -v : enable verbose output
• -s : force the APFS volume to be case-sensitive
• -n : don’t finalize conversion (dry run), leaving the volume in HFS+
• -f : force conversion if the volume is dirty.

Further options are given in its usage information.

Mount an APFS volume with mount_apfs

mount_apfs is an alternative to diskutil mount that mounts a volume, offering a wider range of options, including:

• -u : specifies a UID
• -s : for a snapshot
• -P [file] : for an im4p file
• -M [file] : for an im4m file.

Further options are given in its usage information.

Construct a new APFS volume with newfs_apfs

newfs_apfs is an alternative to diskutil apfs addVolume to construct a new volume, offering a wider range of options, including:

• -r : to specify a volume reserve
• -q : to specify a volume quota
• -U : to specify a uid
• -G : to specify a gid
• -F [fusion] : for a Fusion Drive
• -R : to specify one or more roles for the volume.

Further options are given in its usage information.

I will be delighted to add relevant usage information for any other APFS command tools available in release versions of macOS Sonoma.

Articles in this series

1. Files and clones
2. Directories and names
3. Containers and volumes
4. Snapshots
5. Encryption and sealing
6. Special file types

References

Apple’s APFS Reference (PDF), last revised 22 June 2020.