Package link
Example: package gallery.boomla.net 012082bed9e173a334c59f43b3e9695579affedb5e
A package link mounts another filesystem to the file. The mounted filesystem is immutable, frozen at import time.
The hash above references the rootHash of the mounted filesystem. Note that it does not include the version history of the mounted filesystem, which is important as websites can grow quite large, this helps keeping them small.
When writing the package link, you can use one of 3 hash values:
the same as currently stored in the file link,
the current rootHash of the package website, or
none (leave it out).
When you use the same file link value, you set the link to whatever it was already set to. In this case you are not changing it after all, that's a valid operation.
When the hash is not specified, you are instructing Boomla to fetch the latest rootHash of the remote package and mount it for you.
Using the current active rootHash means you set the package rootHash explicitely, the same that the system would also fetch for you. In fact, it will fetch it anyway but this can simply be used as a safeguard to make sure you don’t mount an unexpected package state by accident.
A package link with an unspecified rootHash would look like this:package gallery.boomla.net.
Linking & linked files
When mounting a filesystem via a package link, you end up having a linking file that is shadowing the linked file - the root file of the linked filesystem. They will have the same path but different file Ids. They can be referenced separately but getting the file by its path will always return the linking file, not the linked file. Another aspect to keep in mind is that you will reference a different file as you walk the filesystem downwards than when you walk it upwards. This is a useful intended behavior.
Use case
Package links are used to install packages on a website. It is often useful to view the documentation of a package that belongs to the exact version you have installed. For that reason, visiting the mounted package (by path) in your browser will pull up its documentation.
Accessing the filesystem root of the mounted package from within the package subtree will thus return the root of the package filesystem. This is needed to keep the package functional, to resolve file types properly. It is said that the package link establishes a new filesystem scope.