documentIdentifierKey description

On HFS / APFS : these two fields are persistent and will survive operations like unmount/mount, device reboot, app relaunch, rename (including reparent), truncate or write.

The fileIdentifierKey uniquely identifies a filesystem object. It might change if the file gets renamed-over (safe-save). In conjunction with generationIdentifierKey it provides a content version that you can use to detect whether a file was modified (renamed-over or written into).

The documentIdentifierKey on the contrary is transferred from the overridden document to the overriding one during a safe-save, and can therefore be used as an identifier to track files across safe-saves.

Other filesystems might not be able to provide stable fileIdentifierKey across mounts or support documentIdentifierKey at all.

Thanks, that’s very helpful.

Is generationIdentifierKey tied to the current filesystem object/inode, or to the logical document identity represented by documentIdentifierKey?

On which common volume/filesystem types are generationIdentifierKey and documentIdentifierKey expected to be supported/reliable? Is there a capability key for this, or should I request the values and treat nil as unsupported?

generationIdentifierKey is tied to the inode.

There is no dedicated volume capability key for either generationIdentifierKey or documentIdentifierKey. The right pattern is to request the values and treat nil as "unsupported on this volume."

You will get these identifiers on HFS+/APFS.

Note that by default documents don't have a documentIdentifierKey. Only files onto which the UF_TRACKED flag (see chflags) would have one.

Since generationIdentifierKey is tied to the inode, should I assume that after safe-save/rename-over the replacement file will have a different generationIdentifierKey even if the resulting file contents are byte-identical to the old file?

In which cases is UF_TRACKED normally set on a file?

After a safe-save you should make no assumption about generationIdentifierKey. It may or may not be have the same value but it is meaningless to compare the generationIdentifierKey fields of files that have different fileIdentifierKey.

Some applications (including system components) might set UF_TRACKED on files when there is a need to follow a document's lifecycle across safe-saves.