Configure file directory boxes

00001004011400 · Info · (manual) · #configuration #manual #zettelstore

Under certain circumstances, it is preferable to further configure a file directory box. This is done by appending query parameters after the base box URI dir://DIR.

The following parameters are supported:

ParameterDescriptionDefault value
type(Sub-) Type of the directory service(value of default-dir-box-type)
rescanTime (in seconds) after which the directory should be scanned fully600
workerNumber of worker that can access the directory in parallel(depends on type)
readonlyAllow only operations that do not change a zettel or create a new zetteln/a


On some operating systems, Zettelstore tries to detect changes to zettel files outside of Zettelstore's control1. On other operating systems, this may be not possible, due to technical limitations. Automatic detection of external changes is also not possible, if zettel files are put on an external service, such as a file server accessed via SMD/CIFS or NFS.

To cope with this uncertainty, Zettelstore provides various internal implementations of a directory box. The default values should match the needs of different users, as explained in the installation part of this manual. The following values are supported:

Is not able to detect external changes. Works on all platforms. Is a little slower than other implementations (up to three times slower).
Automatically detect external changes. Tries to optimize performance, at a little cost of main memory (RAM).


When the parameter type is set to “notify”, Zettelstore automatically detects changes to zettel files that originates from other software. It is done on a “best-effort” basis. Under certain circumstances it is possible that Zettelstore does not detect a change done by another software.

To cope with this unlikely, but still possible event, Zettelstore re-scans periodically the file directory. The time interval is configured by the rescan parameter, e.g.

box-uri-1: dir:///home/zettel?rescan=300

This makes Zettelstore to re-scan the directory /home/zettel/ every 300 seconds, i.e. 5 minutes.

For a Zettelstore with many zettel, re-scanning the directory may take a while, especially if it is stored on a remote computer (e.g. via CIFS/SMB or NFS). In this case, you should adjust the parameter value.

Please note that a directory re-scan invalidates all internal data of a Zettelstore. It might trigger a re-build of the backlink database (and other internal databases). Therefore a large value is preferred.

This value is ignored for other directory box types, such as “simple”.


Internally, Zettelstore parallels concurrent requests for a zettel or its metadata. The number of parallel activities is configured by the worker parameter.

A computer contains a limited number of internal processing units (CPU). Its number ranges from 1 to (currently) 128, e.g. in bigger server environments. Zettelstore typically runs on a system with 1 to 8 CPUs. Access to zettel file is ultimately managed by the underlying operating system. Depending on the hardware and on the type of the directory box, only a limited number of parallel accesses are desirable.

On smaller hardware2, such as the Raspberry Zero➚, a smaller value might be appropriate. Every worker needs some amount of main memory (RAM) and some amount of processing power. On bigger hardware, with some fast file services, a bigger value could result in higher performance, if needed.

For a directory box of type “notify”, the default value is: 7. The directory box type “simple” limits the value to a maximum of 1, i.e. no concurrency is possible with this type of directory box.

For various reasons, the value should be a prime number, with a maximum value of 1499.


Sometimes you may want to provide zettel from a file directory box, but you want to disallow any changes. If you provide the query parameter readonly (with or without a corresponding value), the box will disallow any changes.

box-uri-1: dir:///home/zettel?readonly

If you put the whole Zettelstore in read-only mode, all configured file directory boxes will be in read-only mode too, even if not explicitly configured.

  1. This includes Linux, Windows, and macOS. ↩︎
  2. In comparison to a normal desktop or laptop computer ↩︎