joshhansen/Ghee
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update README.md

Browse source
This commit is contained in:
Josh Hansen 2023-08-10 18:25:07 -07:00
parent cd41dcfd26
commit 0ad2e19562
1 changed files with 42 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
README.md
View file

@ -1,100 +1,108 @@
# Mattress: a command line tool for working with Linux extended attributes (xattrs)
# Ghee: a command line tool for working with Linux extended attributes (xattrs)
The comfiest way to work with Linux extended attributes (xattrs) written in pure Rust
The tastiest way to work with Linux extended attributes (xattrs) written in pure Rust
and made of delicious, fibrous Open Source code.
Mattress provides tools for manipulating xattrs on individual files as well as for working with the filesystem as a document database
Ghee provides tools for manipulating xattrs on individual files as well as for working with the filesystem as a document database
where the filesystem paths act as primary keys and extended attributes provide non-indexed fields.
## History
Mattress was developed in conjunction with the [Audiotater](https://git.disroot.org/joshhansen/audiotater) audio annotation tool.
Ghee was developed in conjunction with the [Audiotater](https://git.disroot.org/joshhansen/audiotater) audio annotation tool.
## License
This software is licensed under GPL version 3 only.
## Conventions
Extended attributes are parsed in a consistent manner by Ghee. Any xattr _not_ preceded by the `trusted`, `security`, `system`, or `user`
namespace will have the `user` namespace by default. For example, xattr `trusted.uptime` remains as is, while `uptime` would become
`user.uptime`.
## Examples
Mattress operates through a set of subcommands, each with a primary function.
Ghee operates through a set of subcommands, each with a primary function.
### Move
Moves xattr values from one path to another.
* `mtr mv path1.txt path2.txt`: move all xattrs from path1.txt to path2.txt
* `mtr mv -f id path1.txt path2.txt`: move xattr `id` from path1.txt to path2.txt
* `mtr mv -f id -f url path1.txt path2.txt`: move xattrs `id` and `url` from path1.txt to path2.txt
* `ghee mv path1.txt path2.txt`: move all xattrs from path1.txt to path2.txt
* `ghee mv -f id path1.txt path2.txt`: move xattr `id` from path1.txt to path2.txt
* `ghee mv -f id -f url path1.txt path2.txt`: move xattrs `id` and `url` from path1.txt to path2.txt
### Copy
Copies xattr values from one path to another.
* `mtr cp path1.txt path2.txt`: copy all xattrs from path1.txt to path2.txt
* `mtr cp -f id path1.txt path2.txt`: copy xattr `id` from path1.txt to path2.txt
* `mtr cp -f id -f url path1.txt path2.txt`: copy xattrs `id` and `url` from path1.txt to path2.txt
* `ghee cp path1.txt path2.txt`: copy all xattrs from path1.txt to path2.txt
* `ghee cp -f id path1.txt path2.txt`: copy xattr `id` from path1.txt to path2.txt
* `ghee cp -f id -f url path1.txt path2.txt`: copy xattrs `id` and `url` from path1.txt to path2.txt
### Remove
Removes xattr values.
* `mtr rm path.txt`: remove all xattrs on path.txt
* `mtr rm -f id path.txt`: remove xattr `id` from path.txt
* `mtr rm -f id -f url path1.txt path2.txt path3.txt`: remove xattrs `id` and `url` from path1.txt, path2.txt, and path3.txt
* `ghee rm path.txt`: remove all xattrs on path.txt
* `ghee rm -f id path.txt`: remove xattr `id` from path.txt
* `ghee rm -f id -f url path1.txt path2.txt path3.txt`: remove xattrs `id` and `url` from path1.txt, path2.txt, and path3.txt
### Set
Sets xattr values.
* `mtr set -s id=123 path1.txt`: set xattr `id` to value `123` on path1.txt
* `mtr set -s id=123 -s url=http://example.com path1.txt path2.txt path3.txt`: set xattr `id` to value `123` and xattr `url` to value `http://example.com` on path1.txt, path2.txt, and path3.txt
* `ghee set -s id=123 path1.txt`: set xattr `id` to value `123` on path1.txt
* `ghee set -s id=123 -s url=http://example.com path1.txt path2.txt path3.txt`: set xattr `id` to value `123` and xattr `url` to value `http://example.com` on path1.txt, path2.txt, and path3.txt
### Get
Get and print xattr values for one or more paths.
Recursively get and print xattr values for one or more paths.
By default, the `get` subcommand outputs a tab-separated table with a column order of `path`, `field`, `value`. The value bytes are written to stdout as-is without decoding.
By default, the `get` subcommand outputs a tab-separated table with a column order of `path`, `field`, `value`.
The value bytes are written to stdout as-is without decoding.
By contrast, when outputting JSON, Mattress attempts to decode values as UTF-8, filling in a default codepoint when the decoding fails.
To opt out of the recursive default, use `--flat`.
* `mtr get path1.txt`: print all xattrs associated with path1.txt as raw (undecoded) TSV
* `mtr get -f id path1.txt`: print xattr `id` and its value on path1.txt as raw (undecoded) TSV
* `mtr get -f id -f url path1.txt path2.txt path3.txt`: print xattrs `id` and `url` and their respective values on path1.txt, path2.txt, and path3.txt as raw (undecoded) TSV
* `ghee get dir`: print all xattrs for directory `dir` and all descendant files and directories, as raw (undecoded) TSV
* `ghee get -f id path1.txt`: print xattr `id` and its value on path1.txt as raw (undecoded) TSV
* `ghee get -f id -f url path1.txt path2.txt path3.txt`: print xattrs `id` and `url` and their respective values on path1.txt, path2.txt, and path3.txt as raw (undecoded) TSV
The `get` command can also output JSON:
The `get` command can also output JSON - in which case values are decoded as UTF-8, filling in a default codepoint when decoding fails:
* `mtr get -j path1.txt`: print all xattrs associated with path1.txt as UTF-8 decoded JSON
* `mtr get -j -f id path1.txt`: print xattr `id` and its value on path1.txt as UTF-8 decoded JSON
* `mtr get -j -f id -f url path1.txt path2.txt path3.txt`: print xattrs `id` and `url` and their respective values on path1.txt, path2.txt, and path3.txt as JSON
* `ghee get -j --flat dir`: print all xattrs for directory `dir` and all descendant files and directories, as UTF-8 decoded JSON
* `ghee get -j -f id path1.txt`: print xattr `id` and its value on path1.txt as UTF-8 decoded JSON
* `ghee get -j -f id -f url path1.txt path2.txt path3.txt`: print xattrs `id` and `url` and their respective values on path1.txt, path2.txt, and path3.txt as JSON
TODO Recursive `get` that benefits from "table" structure / indexing.
By adding `--where` (or `-w`), SQL WHERE-style clauses can be provided to select which files to include in the output. For example,
`ghee get -w age >= 65 ./patients` will select all files under directory `./patients` whose `user.age` attribute is 65 or greater.
### Index
Indexes a "table".
When Mattress acts on a directory as if it were a database table, each file acts as a relational "record" with the primary key coming from the
When Ghee acts on a directory as if it were a database table, each file acts as a relational "record" with the primary key coming from the
subpath under the table directory.
Each file's extended attributes act as the relational attributes, with an overloadable virtual attribute `id` that represents the primary key.
For each subcomponent $i of the primary key, there is also a virtual attribute `id$i`.
Table directories created by Mattress also contain a special xattr `user.mattress.keyname` which gives a user-friendly name for the primary key
Table directories created by Ghee also contain a special xattr `user.ghee.keyname` which gives a user-friendly name for the primary key
component represented by that directory.
Examples:
* `mtr idx -k name ./people ./people-by-name`: recursively reindex the contents of `./people` into a new directory `./people-by-name` with primary key
* `ghee idx -k name ./people ./people-by-name`: recursively reindex the contents of `./people` into a new directory `./people-by-name` with primary key
coming from xattr `name` and files hardlinked to the corresponding files in `./people`.
That means the `./people-by-name` directory's files will have filenames taken from the names of the people as defined in xattr `name`.
The new directory `./people-by-name` will have xattr `user.mattress.keyname=name` so later commands can do efficient index lookups using
The new directory `./people-by-name` will have xattr `user.ghee.keyname=name` so later commands can do efficient index lookups using
user-friendly field names.
* `mtr idx -k region -k name -s ./people-by-name ./people-by-region-and-name`: recursively reindex the contents of `./people-by-name` into a new directory
* `ghee idx -k region -k name -s ./people-by-name ./people-by-region-and-name`: recursively reindex the contents of `./people-by-name` into a new directory
`./people-by-region-and-name` with primary key being the compound of xattr `region` and xattr `name` (in that order) and files hardlinked to the
corresponding files in `./people`, resolved via the hardlinks in `./people-by-name`.
The output directory `./people-by-region-and-name` will have xattr `user.mattress.keyname=region` and each region-named subdirectory will have
xattr `user.mattress.keyname=name`.
The output directory `./people-by-region-and-name` will have xattr `user.ghee.keyname=region` and each region-named subdirectory will have
xattr `user.ghee.keyname=name`.