STree

A directory hierarchy mapping format, similar to mtree, but genuinely much simpler without losing informational value.

Features

No state

Unlike mtree, STree uses no stateful keywords (like mtree's /set and /unset commands), meaning no single line in a manifest has any dependency on any other line, lending itself to greater parallelism.

RHash powered checksum support

Leveraging librhash, stree supports a number of hashing algorithms: SHA256, SHA512, SHA3 (256), SHA3 (512), Blake2b, Blake2s, Blake3, CRC32, and CRC32c. Any number of the algorithms can be used for a single tree, including none.

Optional libmagic integration

The magic feature flag enables two fields obtained through libmagic, for mime type and encoding:

./data.json ... mime.type=application/json mime.encoding=us-ascii ...
./program ... mime.type=application/x-pie-executable mime.encoding=binary ...

Specification

A detailed specification exists in the repository

Example

Below is an example of the base information provided by the format (with no configuration), for the src/ directory in this repository at the time of writing.

#stree 1791085030
. type=directory mode=0755 user=wbr:1000 group=wbr:1000 time.modify=1791083726:564158944
./lib.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791079212:556339543 size=613
./filetype.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791063330:384574196 size=1952
./mode.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791062229:932089478 size=5376
./time.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791065395:818357279 size=3254
./error.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791064004:595482483 size=2387
./stat.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791050597:823710371 size=3100
./util.rs type=regular mode=4644 user=wbr:1000 group=wbr:1000 time.modify=1791054688:263828553 size=4213
./device.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791062862:765944122 size=1829
./checksum.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791049252:731859104 size=3023
./entry.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791081832:755104741 size=12216
./tree.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791081745:648975733 size=4711
./parse.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791077100:269358092 size=4701
./statx.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791074397:785936255 size=808
./verify.rs type=regular mode=0644 user=wbr:1000 group=wbr:1000 time.modify=1791082819:700653838 size=4378

For information about which fields can be enabled, see the API documentation

Motivation

I wanted to use the mtree format to store directory hierarchy information for another project of mine, but I was taken aback when trying to implement the mtree format, due to it requiring a state machine to parse. The /set keyword in mtree is used to apply some given attributes to entries following the statement. I found this very confusing, as this type of syntactic sugar would make sense for a format which was largely hand-written, which mtree is not. The information stored by mtree lines can be fully independent.

It would seem this 'feature' exists because it can theoretically lower the size of a manifest file by collapsing repeated information. At the time (~1989), I'm sure this was a completely rational choice; however, I don't think it is anywhere near as important today, unless you are writing code for embedded systems.

License

The stree library (crate) is licensed under the Mozilla Public License, version 2.0, the stree command line program is licensed under the GNU General Public License, version 3, and the specification is licensed under the GNU Free Documentation License, version 1.3.