I’ve got some apps which I’d like to add to the Finder’s contextual menu, much in the way that Patrick Wardle’s invaluable What Your Sign? does. But I know that Patrick has had problems getting this to work properly, and Apple doesn’t seem to document this type of service – a Finder Sync extension – at all well. My investigations have opened several cans of worms, involving APFS, File Reference URLs, and inodes.

The TL;DR is that any software which stumbles across a hidden file at the top level of the boot volume in APFS amy experience strange behaviour. That applies particularly to FinderSync extensions which are trying to offer general services.

Patrick’s original problem was that he couldn’t get his FinderSync extension to work on anything other than the startup volume. RS Finn kindly solved that in his response on StackOverflow, but it has since come to light that this runs into problems with High Sierra, where forced delays of several seconds can make this all but unworkable.

Patrick eventually traced this to a problem with the hidden file /.file; provided that he excluded that when running on High Sierra, his Finder Sync extension seems to run fine.

I had always thought of /.file, and its sister hidden directory /.vol, as being part of volfs, the hidden file system based on inodes, which are used by Finder Aliases and Bookmarks as persistent file locators. Patrick, though, found references to File Reference URLs, which seemed similar but different.

Macs, whether running the traditional HFS+ or new APFS file system, have several different ways of making lasting and robust records of files. Most of these are based on two numbers: the first indicating the volume on which the file is located, the second a number unique to each file on that volume, known as its inode.

These numbers are used by an alternative file system, volfs, which runs on top of HFS+ and APFS. Instead of using a path of directories, such as
/Users/me/Documents/bigDocs/thisOne.mov, which will break if any of those directories changes name, or the file gets moved, using volfs you might refer to that file as /.vol/16777224/363940889. So long as the file remains on that volume, that volfs path will find it, no matter where it is hidden. This forms the basis of Finder’s Aliases and Bookmarks.

File Reference URLs are more recent, and I think confined to macOS, whilst inodes are common to many types of Unix. They are only really exposed in certain parts of the programming interface to macOS, and users rarely come across them.

When trying to understand what was going on, my first stop was in my tool Precize, which already gives inode and volfs references for files. I thought it should be simple to inspect the File Reference URL and compare it against inode and volfs reference. Unfortunately, working in Swift, that was easier said than done, as Swift 3.0 and later don’t give access to File Reference URLs, apparently because this would make the Swift URL API “very cumbersome”. It’s a long story, but thankfully Frédéric Blondiau had coded a workaround as an extension to the Swift NSURL class.

I butchered Blondiau’s extension to return the File Reference URL for any valid NSURL, and hooked that into Precize, to see what is going on in APFS.

For an ordinary file, its volfs path is likely to be something along the lines of
/.vol/16777224/363940889
with a volume number of 16777224, which is 100 0008 in hexadecimal, and an inode of 363940889. That same file’s File Reference URL would then be
file:///.file/id=6571367.363940889
with a volume number of 6571367 (hex 64 4567), and a file number matching its inode.

A little more checking confirmed that the file number used in a File Reference URL is its inode, but the volume number is different from that used by volfs. Usefully, both the volfs and File Reference URL volume numbers appear constant across boot volumes.

This confirmed my suspicion that both /.file and /.vol are used by volfs, and that volfs is in turn used in File Reference URLs, Aliases, and Bookmarks. But it didn’t show any fundamental difference between HFS+ in Sierra and APFS in High Sierra, which might account for the Finder Sync problem.

Looking at those references for the zero length special file /.file was more revealing. In HFS+/Sierra, the File Reference URL of that file is
file:///.file/id=6571367.363745662
giving it an inode of 363745662, which is nothing special in decimal or hex.

In APFS under High Sierra 10.13.4, though, /.file has a File Reference URL of
file:///.file/id=6571367.42
with an inode of 42 – a very special inode of Douglas Adams’ answer to life, the universe and everything. I don’t think that is coincidence.

Clearly, APFS has changed the hidden file /.file, and software which tries to do anything with that file is at risk of breaking. In this case, it has caught an innocent Finder Sync extension which was just looking to offer its services. If you write or use software which does similar things on APFS, don’t be surprised if it also behaves oddly there.

Here’s that new version of Precize, in case you too want to look at volfs and File Reference URLs: precize10b5
It’s also available in Downloads above.