APFS hard links, symlinks, aliases and clone files: a summary

APFS supports a range of different types of links for files, including hard links, symbolic links (symlinks), Finder aliases, and clone files. This is a short summary of each of them, how they’re implemented in APFS, and how you can create them.

Normal file


Each regular and unlinked file consists of a File System Object and the File Extents that contain the file’s data.

For a file, the File System Object is an inode, with a number unique to that file system (volume), various other values such as its timestamps and ownership information. Also relevant here are the number of siblings that reference that object (normally 1), and a flag to indicate whether that file has ever been cloned.

Hard link


A hard link is actually a single file, with one File System Object, that has two or more references in the form of Siblings. That object has a single set of File Extents, so each of the siblings refers to exactly the same file and data. In the object, the reference count equals the number of siblings; when siblings are deleted, the reference count is decremented, and the object is only removed when that count reaches zero.

Hard links are easily created in Terminal using a command like
ln /Users/myname/Movies/myMovie.mov /Users/myname/Documents/Project1/myNewMovie.mov
to create a new hard link named myNewMovie.mov to the original myMovie.mov.

You can’t create hard links in the Finder, and one of their current quirks is that QuickLook may not show a custom thumbnail for a hard-linked file.

Because they use a single set of File Extents, they essentially take no space on disk.



A symlink is a separate file containing the path to the file that it links to. It thus has its own File System Object, and its own tiny data containing the path to the original. This works well, although moving files around readily breaks any symlinks to them. The inode is unaware of any symlinks to it, so deleting the original file also breaks the symlink.

Symlinks are easily created in Terminal using a command like
ln -s /Users/myname/Movies/myMovie.mov /Users/myname/Documents/Project1/myNewMovie.mov
which creates a tiny file myNewMovie.mov containing the path /Users/myname/Movies/myMovie.mov referring to the file it links to.

You can’t create symlinks in the Finder, and they’re normally shown as links and not the file they link to.

They essentially take no space on disk, although slightly more than hard links, as the symlink file does require storage.


A Finder Alias is a hybrid form of symlink, that also contains inode data so it can resolve its links more robustly. The alias itself has its own File System Object, like a symlink, but its data is more substantial, typically around 1 KB in size.

Aliases are easily created in the Finder, but macOS itself doesn’t contain any command-line support for creating or resolving aliases. For that, use my free command tool alisma. That lets you create an alias with a command of the form
alisma -a sourcefile aliasfile
to create a Finder alias to the file at sourcefile in the alias file aliasfile, and
alisma -p aliasfile
resolves the alias file at aliasfile to return the full path to the original.

Clone files


APFS clone files aren’t links at all, but two separate files, each with their own File System Objects, but only one set of File Extents when they’re first created. Unlike hard links, their objects have a reference count of 1, and no Siblings, although both clones are marked as having been cloned in the inode flags.

As the two clones are progressively changed, the File Extents diverge until they become completely separate, and there’s no data shared between them. Thus, when first created clones occupy essentially no space on disk, but if changed they grow until they take the sum of their individual sizes.

Clone files are easily made in the Finder by duplicating or copying a file within the same file system (volume), and there’s no alternative provided if you want to duplicate a file and its data.

Making a clone file in Terminal requires the -c option in the copy command cp, such as
cp -c originalfile clonefile