# STree
A directory hierarchy mapping format, similar to [mtree](https://man.freebsd.org/cgi/man.cgi?query=mtree&apropos=0&sektion=8&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly&format=html), but genuinely
much simpler without losing informational value.
# Features
### No state
Unlike `mtree`, **STree** uses no stateful keywords (like mtree's [`/set` and `/unset`](https://man.freebsd.org/cgi/man.cgi?query=mtree&apropos=0&sektion=5&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly&format=html) 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types) 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](https://codeberg.org/wreedb/stree/src/branch/main/SPECIFICATION.md) 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](https://docs.rs/stree)
# 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](https://codeberg.org/wreedb/stree/src/branch/main/cli) is licensed under the GNU General Public License, version 3,
and the [specification](https://codeberg.org/wreedb/stree/src/branch/main/SPECIFICATION.md) is licensed under the GNU Free Documentation License, version 1.3.