mirror of
https://github.com/mgree/ffs.git
synced 2024-09-11 19:17:40 +03:00
update cli help, add manpage
This commit is contained in:
Michael Greenberg
parent
1e4ec411f7
commit
93ecc0f644
7
man/Makefile
Normal file
7
man/Makefile
Normal file
@ -0,0 +1,7 @@
|
||||
.PHONY: clean
|
||||
|
||||
ffs.1: ffs.1.md
|
||||
pandoc --standalone --from markdown-smart --to man $< -o $@
|
||||
|
||||
clean:
|
||||
rm ffs.1
|
||||
150
man/ffs.1
Normal file
150
man/ffs.1
Normal file
@ -0,0 +1,150 @@
|
||||
.\" Automatically generated by Pandoc 2.9.1.1
|
||||
.\"
|
||||
.TH "FFS" "1" "" "Version 0.1.0" "File Filesystem Documentation"
|
||||
.hy
|
||||
.SH NAME
|
||||
.PP
|
||||
ffs - the file filesystem
|
||||
.SH SYNOPSIS
|
||||
.PP
|
||||
ffs [\f[I]FLAGS\f[R]/\f[I]OPTIONS\f[R]] [\f[I]INPUT\f[R]]
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
ffs---short for the file filesystem---lets you mount semi-structured
|
||||
data as a filesystem, allowing you to work with modern formats using
|
||||
familiar shell tools.
|
||||
.SS Flags
|
||||
.TP
|
||||
-d, --debug
|
||||
Give debug output on stderr
|
||||
.TP
|
||||
--exact
|
||||
Don\[aq]t add newlines to the end of values that don\[aq]t already have
|
||||
them (or strip them when loading)
|
||||
.TP
|
||||
-i, --in-place
|
||||
Writes the output back over the input file
|
||||
.TP
|
||||
--no-output
|
||||
Disables output of filesystem (normally on stdout)
|
||||
.TP
|
||||
-q, --quiet
|
||||
Quiet mode (turns off all errors and warnings, enables
|
||||
\f[I]--no-output\f[R])
|
||||
.TP
|
||||
--readonly
|
||||
Mounted filesystem will be readonly
|
||||
.TP
|
||||
--unpadded
|
||||
Don\[aq]t pad the numeric names of list elements with zeroes; will not
|
||||
sort properly
|
||||
.TP
|
||||
-h, --help
|
||||
Prints help information (and exits)
|
||||
.TP
|
||||
-V, --version
|
||||
Prints version information (and exits)
|
||||
.SS Options
|
||||
.TP
|
||||
--dirmode \f[I]DIRMODE\f[R]
|
||||
Sets the default mode of directories (parsed as octal; if unspecified,
|
||||
directories will have \f[I]FILEMODE\f[R], with execute bits set when
|
||||
read bits are set) [default: 755]
|
||||
.TP
|
||||
--mode \f[I]FILEMODE\f[R]
|
||||
Sets the default mode of files (parsed as octal) [default: 644]
|
||||
.TP
|
||||
-g, --gid \f[I]GID\f[R]
|
||||
Sets the group id of the generated filesystem (defaults to current
|
||||
effective group id)
|
||||
.TP
|
||||
-m, --mount \f[I]MOUNT\f[R]
|
||||
Sets the mountpoint; will be inferred when using a file, but must be
|
||||
specified when running on stdin
|
||||
.TP
|
||||
-o, --output \f[I]OUTPUT\f[R]
|
||||
Sets the output file for saving changes (defaults to stdout)
|
||||
.TP
|
||||
--completions \f[I]SHELL\f[R]
|
||||
Generate shell completions and exit [possible values: bash, fish, zsh]
|
||||
.TP
|
||||
-s, --source \f[I]SOURCE_FORMAT\f[R]
|
||||
Specify the source format explicitly (by default, automatically inferred
|
||||
from filename extension) [possible values: json, toml, yaml]
|
||||
.TP
|
||||
-t, --target \f[I]TARGET_FORMAT\f[R]
|
||||
Specify the target format explicitly (by default, automatically inferred
|
||||
from filename extension) [possible values: json, toml, yaml]
|
||||
.TP
|
||||
-u, --uid \f[I]UID\f[R]
|
||||
Sets the user id of the generated filesystem (defaults to current
|
||||
effective user id)
|
||||
.SS Arguments
|
||||
.TP
|
||||
\f[I]INPUT\f[R]
|
||||
Sets the input file (use \[aq]-\[aq] for stdin) [default: -]
|
||||
.SH ENVIRONMENT
|
||||
.TP
|
||||
RUST_LOG
|
||||
Configures tracing output.
|
||||
Use the format \f[I]key\f[R]=\f[I]level\f[R], where \f[I]key\f[R] should
|
||||
probably be \f[I]ffs\f[R] and \f[I]level\f[R] should be one of
|
||||
\f[I]error\f[R], \f[I]warn\f[R], \f[I]info\f[R], \f[I]debug\f[R], or
|
||||
\f[I]trace\f[R].
|
||||
The default is \f[I]ffs=warn\f[R].
|
||||
Setting \f[I]-q\f[R] turns off all output; setting \f[I]-d\f[R] sets
|
||||
\f[I]ffs=debug\f[R].
|
||||
.SH EXAMPLES
|
||||
.PP
|
||||
The general workflow is to run \f[I]ffs\f[R], do some work, and then
|
||||
unmount the mountpoint using \f[I]umount\f[R].
|
||||
It\[aq]s typical to run \f[I]ffs\f[R] in the background, since the
|
||||
program will not terminate until the userspace filesystem is unmounted.
|
||||
.PP
|
||||
By default, \f[I]ffs\f[R] will work off of stdin, in which case you must
|
||||
specify a mountpoint with \f[I]-m\f[R].
|
||||
If you have a mountpoint/directory \f[I]mnt\f[R], you can download
|
||||
information on GitHub commits, work with them, and save the modified
|
||||
output to \f[I]commits.json\f[R] by running:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
curl https://api.github.com/repos/mgree/ffs/commits | ffs -m mnt -o commits.json
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
If you had already downloaded the file to \f[I]commits.json\f[R], you
|
||||
could simply run:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
ffs -i commits.json
|
||||
# do edits in commits directory
|
||||
umount commits
|
||||
# changes are written back to commits.json (-i is in-place mode)
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
To mount a JSON file and write back out a YAML file, you could run:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
ffs -o output_data.yaml input_data.json
|
||||
# do edits in the input_data directory ffs created
|
||||
umount input_data
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
When filenames are present, extensions will be used to infer the format
|
||||
being used.
|
||||
You can specify the source and target formats explicitly with
|
||||
\f[I]--source\f[R] and \f[I]--target\f[R], respectively.
|
||||
.SH BUGS
|
||||
.PP
|
||||
See <https://github.com/mgree/ffs/issues>.
|
||||
.SH LICENSE
|
||||
.PP
|
||||
Copyright 2021 (c) Michael Greenberg.
|
||||
GPL-3.0 licensed.
|
||||
.SH AUTHORS
|
||||
Michael Greenberg.
|
||||
166
man/ffs.1.md
Normal file
166
man/ffs.1.md
Normal file
@ -0,0 +1,166 @@
|
||||
% FFS(1) Version 0.1.0 | File Filesystem Documentation
|
||||
% Michael Greenberg
|
||||
|
||||
# NAME
|
||||
|
||||
ffs - the file filesystem
|
||||
|
||||
# SYNOPSIS
|
||||
|
||||
| ffs \[*FLAGS*/*OPTIONS*\] \[*INPUT*\]
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
ffs---short for the file filesystem---lets you mount semi-structured
|
||||
data as a filesystem, allowing you to work with modern formats using
|
||||
familiar shell tools.
|
||||
|
||||
## Flags
|
||||
|
||||
-d, --debug
|
||||
|
||||
: Give debug output on stderr
|
||||
|
||||
--exact
|
||||
|
||||
: Don't add newlines to the end of values that don't already have them
|
||||
(or strip them when loading)
|
||||
|
||||
-i, --in-place
|
||||
|
||||
: Writes the output back over the input file
|
||||
|
||||
--no-output
|
||||
|
||||
: Disables output of filesystem (normally on stdout)
|
||||
|
||||
-q, --quiet
|
||||
|
||||
: Quiet mode (turns off all errors and warnings, enables
|
||||
*--no-output*)
|
||||
|
||||
--readonly
|
||||
|
||||
: Mounted filesystem will be readonly
|
||||
|
||||
--unpadded
|
||||
|
||||
: Don't pad the numeric names of list elements with zeroes; will not
|
||||
sort properly
|
||||
|
||||
-h, --help
|
||||
|
||||
: Prints help information (and exits)
|
||||
|
||||
-V, --version
|
||||
|
||||
: Prints version information (and exits)
|
||||
|
||||
## Options
|
||||
--dirmode *DIRMODE*
|
||||
|
||||
: Sets the default mode of directories (parsed as octal; if
|
||||
unspecified, directories will have *FILEMODE*, with execute bits set
|
||||
when read bits are set) [default: 755]
|
||||
|
||||
--mode *FILEMODE*
|
||||
|
||||
: Sets the default mode of files (parsed as octal) [default: 644]
|
||||
|
||||
-g, --gid *GID*
|
||||
|
||||
: Sets the group id of the generated filesystem (defaults to current
|
||||
effective group id)
|
||||
|
||||
-m, --mount *MOUNT*
|
||||
|
||||
: Sets the mountpoint; will be inferred when using a file, but must be
|
||||
specified when running on stdin
|
||||
|
||||
-o, --output *OUTPUT*
|
||||
|
||||
: Sets the output file for saving changes (defaults to stdout)
|
||||
|
||||
--completions *SHELL*
|
||||
|
||||
: Generate shell completions and exit [possible values: bash, fish,
|
||||
zsh]
|
||||
|
||||
-s, --source *SOURCE_FORMAT*
|
||||
|
||||
: Specify the source format explicitly (by default, automatically
|
||||
inferred from filename extension) [possible values: json, toml,
|
||||
yaml]
|
||||
|
||||
-t, --target *TARGET_FORMAT*
|
||||
|
||||
: Specify the target format explicitly (by default, automatically
|
||||
inferred from filename extension) [possible values: json, toml,
|
||||
yaml]
|
||||
|
||||
-u, --uid *UID*
|
||||
|
||||
: Sets the user id of the generated filesystem (defaults to current
|
||||
effective user id)
|
||||
|
||||
## Arguments
|
||||
|
||||
*INPUT*
|
||||
|
||||
: Sets the input file (use '-' for stdin) [default: -]
|
||||
|
||||
# ENVIRONMENT
|
||||
|
||||
RUST_LOG
|
||||
|
||||
: Configures tracing output. Use the format *key*=*level*, where *key*
|
||||
should probably be *ffs* and *level* should be one of *error*,
|
||||
*warn*, *info*, *debug*, or *trace*. The default is
|
||||
*ffs=warn*. Setting *-q* turns off all output; setting *-d* sets
|
||||
*ffs=debug*.
|
||||
|
||||
# EXAMPLES
|
||||
|
||||
The general workflow is to run *ffs*, do some work, and then unmount
|
||||
the mountpoint using *umount*. It's typical to run *ffs* in the
|
||||
background, since the program will not terminate until the userspace
|
||||
filesystem is unmounted.
|
||||
|
||||
By default, *ffs* will work off of stdin, in which case you must
|
||||
specify a mountpoint with *-m*. If you have a mountpoint/directory
|
||||
*mnt*, you can download information on GitHub commits, work with them,
|
||||
and save the modified output to *commits.json* by running:
|
||||
|
||||
```
|
||||
curl https://api.github.com/repos/mgree/ffs/commits | ffs -m mnt -o commits.json
|
||||
```
|
||||
|
||||
If you had already downloaded the file to *commits.json*, you could simply run:
|
||||
|
||||
```
|
||||
ffs -i commits.json
|
||||
# do edits in commits directory
|
||||
umount commits
|
||||
# changes are written back to commits.json (-i is in-place mode)
|
||||
```
|
||||
|
||||
To mount a JSON file and write back out a YAML file, you could run:
|
||||
|
||||
```
|
||||
ffs -o output_data.yaml input_data.json
|
||||
# do edits in the input_data directory ffs created
|
||||
umount input_data
|
||||
```
|
||||
|
||||
When filenames are present, extensions will be used to infer the
|
||||
format being used. You can specify the source and target formats
|
||||
explicitly with *--source* and *--target*, respectively.
|
||||
|
||||
# BUGS
|
||||
|
||||
See
|
||||
[https://github.com/mgree/ffs/issues](https://github.com/mgree/ffs/issues).
|
||||
|
||||
# LICENSE
|
||||
|
||||
Copyright 2021 (c) Michael Greenberg. GPL-3.0 licensed.
|
||||
@ -46,14 +46,14 @@ pub fn app() -> App<'static, 'static> {
|
||||
)
|
||||
.arg(
|
||||
Arg::with_name("FILEMODE")
|
||||
.help("Sets the default mode of files (parsed as octal; defaults to 644; if unspecified, directories will have this mode with execute bits set when read bits are set)")
|
||||
.help("Sets the default mode of files (parsed as octal)")
|
||||
.long("mode")
|
||||
.takes_value(true)
|
||||
.default_value("644")
|
||||
)
|
||||
.arg(
|
||||
Arg::with_name("DIRMODE")
|
||||
.help("Sets the default mode of directories (parsed as octal; defaults to 755; )")
|
||||
.help("Sets the default mode of directories (parsed as octal; if unspecified, directories will have FILEMODE with execute bits set when read bits are set)")
|
||||
.long("dirmode")
|
||||
.takes_value(true)
|
||||
.default_value("755")
|
||||
@ -119,7 +119,7 @@ pub fn app() -> App<'static, 'static> {
|
||||
)
|
||||
.arg(
|
||||
Arg::with_name("INPUT")
|
||||
.help("Sets the input file (defaults to '-', meaning STDIN)")
|
||||
.help("Sets the input file ('-' means STDIN)")
|
||||
.default_value("-")
|
||||
.index(1),
|
||||
)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user