APFS, safe saves, inodes and the volfs file system

Whether your Mac is booted from an APFS volume, or HFS+, and regardless of what storage is connected to it, there are other file systems you can use without so much as changing format. The most useful of these are based on a scheme in which each volume has a unique number, and every file and folder has another number unique to that volume – these are inodes in the volfs file system. Instead of a path such as /Users/me/Documents/bigDocs/thisOne.mov, you can instead refer to that file as /.vol/16777224/363940889.

Wherever you might move that item within the same volume, and however you might change its name, using that volfs path will always locate it.

Inodes and volfs paths aren’t intended for use in the GUI, and aren’t revealed in the Finder’s Get Info dialog, for instance. Unless you have very unusual ability, remembering two very large numbers isn’t a good thing to try. But where a command or script needs to be able to locate precisely the same file wherever it’s gone and whatever name it’s now going under, there’s nothing comparable. Inodes and volfs not only work across different file systems such as APFS and HFS+, but they’re also cross-platform, and common among varieties of Unix and Linux. There’s even an equivalent, the file ID, in Windows.

Converting to and from inodes

The simplest ways of obtaining inodes and so building volfs paths in Terminal are using the -i option to the ls command, and for individual items using stat:
ls -i lists each item in the current directory, giving its inode first, e.g.
22084095 00swift
13679656 Microsoft User Data
22075835 Wolfram Mathematica

and so on;
stat myfile.text returns
16777220 36849933 -rw-r--r-- 1 hoakley staff […] myfile.text
where the first number is the volume inode, and the second is the inode of that item, or /.vol/16777220/36849933


In the GUI, use my free utility Precize, which shows you a great deal more too.

You can reverse the lookup using the deprecated tool GetFileInfo, which is still available in Mojave:
GetFileInfo /.vol/16777220/39351810 returns a list of metadata such as
file: "/Users/hoakley/Documents/zTestFile1.rtf"
type: "\0\0\0\0"
creator: "\0\0\0\0"
attributes: avbstclinmedz
created: 09/03/2019 13:50:32
modified: 09/03/2019 13:50:32

APFS stores the inode of each file system object in its record header, in j_inode_key_t/j_key_t


Volume numbers start at around hexadecimal 1000000, and the regular internal boot volume is typically given the decimal number 16777220 (0x1000004), in APFS. Within those volumes are two hidden special items, /.file and /.vol/, which can be used to determine the volume inode of that volume. Back in High Sierra’s version of APFS, the inode of the special /.file object used to be 42, but this has become a more prosaic number in Mojave.

The biggest drawback with using inodes and volfs is that file saving practice keeps changing the inode of a file each time that it’s saved. This is inevitable when a safe or atomic save technique is used: the file is first saved under a temporary name; when that has completed successfully, the original file is deleted and the saved file renamed as the original. Because the saved file is written out to a new file system object, it’s given a new inode number. Unfortunately this remains standard practice in Apple’s AppKit, for example, even when it’s saving files to an APFS volume.

One of the great strengths of APFS is its use of copy on write, which makes such safe saves unnecessary, the file system doing essentially the same thing but at a lower level: the changed file is written out to a different block of storage, and on successful completion of that the file system metadata are changed to point to that new storage location. Because APFS doesn’t create a new file system object in the process, the original inode number is preserved.

Tracking inodes is perhaps the only way that you can check whether apps still ‘safe save’ or leave it to APFS copy on write. Check a document’s volfs path in Precize, and check it again after modifying its contents and saving the changed file. If the volfs path changes, then the app or a framework such as AppKit created a new file into which the document’s data was saved. If the volfs path remains identical but the contents have changed, then that should have been managed by APFS copy on write instead.

Links and FileRefURL

Hard links show identical inodes to their originals, while symbolic links and Finder aliases both have their own inode numbers, as distinct file system objects which in turn point to other objects. Finder aliases and their data equivalent, Bookmarks, contain the inode number of that item in their _NSURLFileIDKey field. However, their NSURLDocumentIdentifierKey isn’t an inode number, even though it might look like one.

For further confusion, you may also come across Apple’s File Reference URL, which looks like a volfs path, with two reference numbers separated by a period/stop. The first number is a different volume reference number, not the volume inode, but the second number is that item’s inode number.