Skip to content

Commit 93ecc0f

Browse files
mgreemgree
committed
update cli help, add manpage
1 parent 1e4ec41 commit 93ecc0f

File tree

4 files changed

+326
-3
lines changed

4 files changed

+326
-3
lines changed

‎man/Makefile

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.PHONY: clean
2+
3+
ffs.1: ffs.1.md
4+
pandoc --standalone --from markdown-smart --to man $< -o $@
5+
6+
clean:
7+
rm ffs.1

‎man/ffs.1

+150
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
.\" Automatically generated by Pandoc 2.9.1.1
2+
.\"
3+
.TH "FFS" "1" "" "Version 0.1.0" "File Filesystem Documentation"
4+
.hy
5+
.SH NAME
6+
.PP
7+
ffs - the file filesystem
8+
.SH SYNOPSIS
9+
.PP
10+
ffs [\f[I]FLAGS\f[R]/\f[I]OPTIONS\f[R]] [\f[I]INPUT\f[R]]
11+
.SH DESCRIPTION
12+
.PP
13+
ffs---short for the file filesystem---lets you mount semi-structured
14+
data as a filesystem, allowing you to work with modern formats using
15+
familiar shell tools.
16+
.SS Flags
17+
.TP
18+
-d, --debug
19+
Give debug output on stderr
20+
.TP
21+
--exact
22+
Don\[aq]t add newlines to the end of values that don\[aq]t already have
23+
them (or strip them when loading)
24+
.TP
25+
-i, --in-place
26+
Writes the output back over the input file
27+
.TP
28+
--no-output
29+
Disables output of filesystem (normally on stdout)
30+
.TP
31+
-q, --quiet
32+
Quiet mode (turns off all errors and warnings, enables
33+
\f[I]--no-output\f[R])
34+
.TP
35+
--readonly
36+
Mounted filesystem will be readonly
37+
.TP
38+
--unpadded
39+
Don\[aq]t pad the numeric names of list elements with zeroes; will not
40+
sort properly
41+
.TP
42+
-h, --help
43+
Prints help information (and exits)
44+
.TP
45+
-V, --version
46+
Prints version information (and exits)
47+
.SS Options
48+
.TP
49+
--dirmode \f[I]DIRMODE\f[R]
50+
Sets the default mode of directories (parsed as octal; if unspecified,
51+
directories will have \f[I]FILEMODE\f[R], with execute bits set when
52+
read bits are set) [default: 755]
53+
.TP
54+
--mode \f[I]FILEMODE\f[R]
55+
Sets the default mode of files (parsed as octal) [default: 644]
56+
.TP
57+
-g, --gid \f[I]GID\f[R]
58+
Sets the group id of the generated filesystem (defaults to current
59+
effective group id)
60+
.TP
61+
-m, --mount \f[I]MOUNT\f[R]
62+
Sets the mountpoint; will be inferred when using a file, but must be
63+
specified when running on stdin
64+
.TP
65+
-o, --output \f[I]OUTPUT\f[R]
66+
Sets the output file for saving changes (defaults to stdout)
67+
.TP
68+
--completions \f[I]SHELL\f[R]
69+
Generate shell completions and exit [possible values: bash, fish, zsh]
70+
.TP
71+
-s, --source \f[I]SOURCE_FORMAT\f[R]
72+
Specify the source format explicitly (by default, automatically inferred
73+
from filename extension) [possible values: json, toml, yaml]
74+
.TP
75+
-t, --target \f[I]TARGET_FORMAT\f[R]
76+
Specify the target format explicitly (by default, automatically inferred
77+
from filename extension) [possible values: json, toml, yaml]
78+
.TP
79+
-u, --uid \f[I]UID\f[R]
80+
Sets the user id of the generated filesystem (defaults to current
81+
effective user id)
82+
.SS Arguments
83+
.TP
84+
\f[I]INPUT\f[R]
85+
Sets the input file (use \[aq]-\[aq] for stdin) [default: -]
86+
.SH ENVIRONMENT
87+
.TP
88+
RUST_LOG
89+
Configures tracing output.
90+
Use the format \f[I]key\f[R]=\f[I]level\f[R], where \f[I]key\f[R] should
91+
probably be \f[I]ffs\f[R] and \f[I]level\f[R] should be one of
92+
\f[I]error\f[R], \f[I]warn\f[R], \f[I]info\f[R], \f[I]debug\f[R], or
93+
\f[I]trace\f[R].
94+
The default is \f[I]ffs=warn\f[R].
95+
Setting \f[I]-q\f[R] turns off all output; setting \f[I]-d\f[R] sets
96+
\f[I]ffs=debug\f[R].
97+
.SH EXAMPLES
98+
.PP
99+
The general workflow is to run \f[I]ffs\f[R], do some work, and then
100+
unmount the mountpoint using \f[I]umount\f[R].
101+
It\[aq]s typical to run \f[I]ffs\f[R] in the background, since the
102+
program will not terminate until the userspace filesystem is unmounted.
103+
.PP
104+
By default, \f[I]ffs\f[R] will work off of stdin, in which case you must
105+
specify a mountpoint with \f[I]-m\f[R].
106+
If you have a mountpoint/directory \f[I]mnt\f[R], you can download
107+
information on GitHub commits, work with them, and save the modified
108+
output to \f[I]commits.json\f[R] by running:
109+
.IP
110+
.nf
111+
\f[C]
112+
curl https://api.github.com/repos/mgree/ffs/commits | ffs -m mnt -o commits.json
113+
\f[R]
114+
.fi
115+
.PP
116+
If you had already downloaded the file to \f[I]commits.json\f[R], you
117+
could simply run:
118+
.IP
119+
.nf
120+
\f[C]
121+
ffs -i commits.json
122+
# do edits in commits directory
123+
umount commits
124+
# changes are written back to commits.json (-i is in-place mode)
125+
\f[R]
126+
.fi
127+
.PP
128+
To mount a JSON file and write back out a YAML file, you could run:
129+
.IP
130+
.nf
131+
\f[C]
132+
ffs -o output_data.yaml input_data.json
133+
# do edits in the input_data directory ffs created
134+
umount input_data
135+
\f[R]
136+
.fi
137+
.PP
138+
When filenames are present, extensions will be used to infer the format
139+
being used.
140+
You can specify the source and target formats explicitly with
141+
\f[I]--source\f[R] and \f[I]--target\f[R], respectively.
142+
.SH BUGS
143+
.PP
144+
See <https://github.com/mgree/ffs/issues>.
145+
.SH LICENSE
146+
.PP
147+
Copyright 2021 (c) Michael Greenberg.
148+
GPL-3.0 licensed.
149+
.SH AUTHORS
150+
Michael Greenberg.

‎man/ffs.1.md

+166
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
% FFS(1) Version 0.1.0 | File Filesystem Documentation
2+
% Michael Greenberg
3+
4+
# NAME
5+
6+
ffs - the file filesystem
7+
8+
# SYNOPSIS
9+
10+
| ffs \[*FLAGS*/*OPTIONS*\] \[*INPUT*\]
11+
12+
# DESCRIPTION
13+
14+
ffs---short for the file filesystem---lets you mount semi-structured
15+
data as a filesystem, allowing you to work with modern formats using
16+
familiar shell tools.
17+
18+
## Flags
19+
20+
-d, --debug
21+
22+
: Give debug output on stderr
23+
24+
--exact
25+
26+
: Don't add newlines to the end of values that don't already have them
27+
(or strip them when loading)
28+
29+
-i, --in-place
30+
31+
: Writes the output back over the input file
32+
33+
--no-output
34+
35+
: Disables output of filesystem (normally on stdout)
36+
37+
-q, --quiet
38+
39+
: Quiet mode (turns off all errors and warnings, enables
40+
*--no-output*)
41+
42+
--readonly
43+
44+
: Mounted filesystem will be readonly
45+
46+
--unpadded
47+
48+
: Don't pad the numeric names of list elements with zeroes; will not
49+
sort properly
50+
51+
-h, --help
52+
53+
: Prints help information (and exits)
54+
55+
-V, --version
56+
57+
: Prints version information (and exits)
58+
59+
## Options
60+
--dirmode *DIRMODE*
61+
62+
: Sets the default mode of directories (parsed as octal; if
63+
unspecified, directories will have *FILEMODE*, with execute bits set
64+
when read bits are set) [default: 755]
65+
66+
--mode *FILEMODE*
67+
68+
: Sets the default mode of files (parsed as octal) [default: 644]
69+
70+
-g, --gid *GID*
71+
72+
: Sets the group id of the generated filesystem (defaults to current
73+
effective group id)
74+
75+
-m, --mount *MOUNT*
76+
77+
: Sets the mountpoint; will be inferred when using a file, but must be
78+
specified when running on stdin
79+
80+
-o, --output *OUTPUT*
81+
82+
: Sets the output file for saving changes (defaults to stdout)
83+
84+
--completions *SHELL*
85+
86+
: Generate shell completions and exit [possible values: bash, fish,
87+
zsh]
88+
89+
-s, --source *SOURCE_FORMAT*
90+
91+
: Specify the source format explicitly (by default, automatically
92+
inferred from filename extension) [possible values: json, toml,
93+
yaml]
94+
95+
-t, --target *TARGET_FORMAT*
96+
97+
: Specify the target format explicitly (by default, automatically
98+
inferred from filename extension) [possible values: json, toml,
99+
yaml]
100+
101+
-u, --uid *UID*
102+
103+
: Sets the user id of the generated filesystem (defaults to current
104+
effective user id)
105+
106+
## Arguments
107+
108+
*INPUT*
109+
110+
: Sets the input file (use '-' for stdin) [default: -]
111+
112+
# ENVIRONMENT
113+
114+
RUST_LOG
115+
116+
: Configures tracing output. Use the format *key*=*level*, where *key*
117+
should probably be *ffs* and *level* should be one of *error*,
118+
*warn*, *info*, *debug*, or *trace*. The default is
119+
*ffs=warn*. Setting *-q* turns off all output; setting *-d* sets
120+
*ffs=debug*.
121+
122+
# EXAMPLES
123+
124+
The general workflow is to run *ffs*, do some work, and then unmount
125+
the mountpoint using *umount*. It's typical to run *ffs* in the
126+
background, since the program will not terminate until the userspace
127+
filesystem is unmounted.
128+
129+
By default, *ffs* will work off of stdin, in which case you must
130+
specify a mountpoint with *-m*. If you have a mountpoint/directory
131+
*mnt*, you can download information on GitHub commits, work with them,
132+
and save the modified output to *commits.json* by running:
133+
134+
```
135+
curl https://api.github.com/repos/mgree/ffs/commits | ffs -m mnt -o commits.json
136+
```
137+
138+
If you had already downloaded the file to *commits.json*, you could simply run:
139+
140+
```
141+
ffs -i commits.json
142+
# do edits in commits directory
143+
umount commits
144+
# changes are written back to commits.json (-i is in-place mode)
145+
```
146+
147+
To mount a JSON file and write back out a YAML file, you could run:
148+
149+
```
150+
ffs -o output_data.yaml input_data.json
151+
# do edits in the input_data directory ffs created
152+
umount input_data
153+
```
154+
155+
When filenames are present, extensions will be used to infer the
156+
format being used. You can specify the source and target formats
157+
explicitly with *--source* and *--target*, respectively.
158+
159+
# BUGS
160+
161+
See
162+
[https://github.com/mgree/ffs/issues](https://github.com/mgree/ffs/issues).
163+
164+
# LICENSE
165+
166+
Copyright 2021 (c) Michael Greenberg. GPL-3.0 licensed.

‎src/cli.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -46,14 +46,14 @@ pub fn app() -> App<'static, 'static> {
4646
)
4747
.arg(
4848
Arg::with_name("FILEMODE")
49-
.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)")
49+
.help("Sets the default mode of files (parsed as octal)")
5050
.long("mode")
5151
.takes_value(true)
5252
.default_value("644")
5353
)
5454
.arg(
5555
Arg::with_name("DIRMODE")
56-
.help("Sets the default mode of directories (parsed as octal; defaults to 755; )")
56+
.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)")
5757
.long("dirmode")
5858
.takes_value(true)
5959
.default_value("755")
@@ -119,7 +119,7 @@ pub fn app() -> App<'static, 'static> {
119119
)
120120
.arg(
121121
Arg::with_name("INPUT")
122-
.help("Sets the input file (defaults to '-', meaning STDIN)")
122+
.help("Sets the input file ('-' means STDIN)")
123123
.default_value("-")
124124
.index(1),
125125
)

0 commit comments

Comments
 (0)