File Links

Like traditional operating systems, Boomla supports file links.

No automatic dereferencing

Traditional operating systems have special file types for links. Not in Boomla, where every file is created equal. This has important consequences. When you open a symlink on Linux, it’s automatically dereferenced. You loose context. You can’t tell which file you opened, you can only tell which file you ended up working with. A Boomla file has a special link property. File links are not dereferenced by default. This makes it so much easier to work with them.

Links are only followed when you access the file’s properties, attributes, body or children. It also depends on what link mode the file is using and what you are accessing.

For example, accessing the link property of the file never dereferences it, which is very important as you may realize.

Link mode: PACKAGE

A package link mounts (imports) another filesystem into a file. The mount is immutable, frozen at import time.

Example: package 01e36bd30520786257eebd3bc0078796c8eaf506f8

The hash above references the hash of the mounted filesystem. Note that it does not include the version history of the imported filesystem, which is important as websites can grow quite big, this helps keeping them small.

When updating the link, you can use one of 3 hash values: unchanged, latest, none. Unchanged means, you set the link to whatever it was already set to. Well, in this case you are not changing it after all. None means, you can leave it empty. In this case, the system will fetch the hash of the remote website and fill it in for you. Latest means you set the latest hash of the remove website explicitely, the same that the system would also fetch for you. In fact, it will fetch it, this can simply be used as a safeguard to make sure you don’t set it to an unexpected value by accident.

Example when hash is not provided: package

Note that when importing a filesystem, you end up having a linking file that is shadowing the root file of the linked filesystem. This is important to keep in mind, as you will end up working with a different file as you walk the filesystem upwards or downwards. This is not a bug, this is a very useful, intentional behaviour.

You can also follow links in both ways, which gives you full control.


Package links are most often used to install apps on your system. It is often very useful to view the documentation of your package that belongs to the exact version you have installed. For that reason, visiting the path of the imported package will land you on a website (documentation) that exactly matches the one you imported it from.

Accessing the filesystem root of the imported package from within the package subtree will thus return the root of the package filesystem. This is needed to keep the imported package functional, to resolve file types properly.

Link mode: REFERENCE

A reference link simply references another file by path. The link is never automatically followed thus all properties, attributes, body and children are accessed on the linking file. You have to explicitely follow the linking file to work with the referenced file.