This is a small utility for managing symlink farms. It takes a "farm" directory and any number of "data" directories, and creates (or updates) the union of the data directories in the farm directory by placing symlinks to data directories.
It is similar to
union mounts (overlay/overlayfs) -- but works without system privileges; it is not live, but can then again err out on duplicate files rather than picking the highest ranking
(x)stow -- but it is buggy with symlink farms as sources (cf. https://sourceforge.net/p/xstow/bugs/8/). Unlike stow, this always takes a full list of to-be-installed "packages", removes files that have vanished from the sources, and errs out on files not associated with any source.
This tries to be
in that order. Correctness means not deleting anything that can not plausibly have been an entry in a removed data source (ie. it only removes symlinks whose targets end in their own path relative to the farm), and creating as few symlinks as possible (even when there used to be an a/ in two data sources and one data sources' gets removed, a/ at the farm is removed and turned into a symlink).
Ease of maintenance over efficiency means that no efforts are made to to use
components not yet in the standard library, like using the [statx] system
call, or passing around file descriptors to allow openat (if that'd work at
all in the presence of large directories).
This program does not recurse on stack, but keep a to-do list of unfinished paths. It keeps the number of file system access operations to a reasonable minimum to fullfil its task.
When the program runs to completion and farm and data were unchanged since its start, a second invocation will not cause any file system writes. A second invocation may cause file system writes if the first was not successful (eg. aborted due to the presence of an unidentified file in the farm), as the sequence of file operations is not necessarily deterministic. (The implementation may be changed in the future to spool up such errors and only abort when nothing else is left to do).
The program provides detailed logging on demand, and meaningful messages on errors (including ones stemming from changes to the file system during its run time) rather than plainly panicking on them.
The farm directory can not have a trailing slash. It's usually not an issue, but a slash breaks the program's ability to make the farm point directly to the single present data directory, or remove such a symlink.
Verbosity settings start at "errors only"; warnings are not shown unless a
-v is given, and actual information is only printed when -vv or -vvv is
given.