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

This project is licensed under the Mozilla Public License, version 2.0 (MPL-2.0)